📚 Add Files and Projects section to user guide

🐛 Fix translation on rename token

docs/user-guide/account-teams/index.njk

@@ -19,6 +19,12 @@ desc: Begin with the Penpot user guide! Get quickstarts, shortcuts, and tutorial
       <p>Create and manage your teams</p>
     </a>
   </li>
+  <li>
+    <a href="/user-guide/account-teams/projects-files">
+      <h2>Projects and Files →</h2>
+      <p>Organize your work with projects and files</p>
+    </a>
+  </li>
   <li>
     <a href="/user-guide/account-teams/comments/">
       <h2>Comments →</h2>

docs/user-guide/account-teams/projects-files.njk

@@ -0,0 +1,107 @@
+---
+title: Projects and Files
+order: 3
+desc: Learn how to organize your work in Penpot. Create, manage and organize projects and files, work with drafts, and handle deleted items.
+---
+
+<h1 id="projects-files">Projects and Files</h1>
+<p class="main-paragraph">Projects and files are the core organizational structure in Penpot. Projects work like folders that contain multiple design files, helping you organize your work efficiently. Files are your actual design documents where you create boards, pages, and all your design elements.</p>
+<p class="main-paragraph">Understanding how to manage projects and files will help you keep your workspace organized and make it easier to collaborate with your team.</p>
+
+<h2 id="projects-management">Projects</h2>
+<p>Projects are containers that help you organize and group related design files together. Think of them as folders in a file system. You can create as many projects as you need to organize your work by client, product, feature, or any other structure that fits your workflow.</p>
+<p>If you're working with others, projects should be created inside a team so that team members can collaborate on the files within them. Projects created in your personal space ("Your Penpot") remain private to you.</p>
+<figure>
+  <img src="/img/files-projects/01-projects.webp" alt="Projects view in dashboard" />
+</figure>
+
+<h3 id="create-project">Create a project</h3>
+<p>To create a new project, use the <strong>+ New project</strong> button in the dashboard. You can also use the keyboard shortcut <kbd>+</kbd> when you're on the dashboard. A dialog will appear where you can enter the project name. Once created, the project will appear in your projects list.</p>
+<p>When you create a project, you can immediately start adding files to it, or create files first and move them into the project later.</p>
+
+<h3 id="edit-project">Edit a project</h3>
+<p>To edit a project's name, right-click on the project in the sidebar or click the three-dot menu next to the project name. Select <strong>Edit</strong> or <strong>Rename</strong> to change the project name. You can also update the project's profile picture from the same menu.</p>
+
+<h3 id="pin-project">Pin a project</h3>
+<p>Projects can be pinned to the sidebar for quick access. Right-click on a project and select <strong>Pin</strong> to keep it visible in the sidebar even when you have many projects. Pinned projects appear at the top of your projects list for easy access.</p>
+<p>To unpin a project, right-click on it and select <strong>Unpin</strong>. The project will remain in your list but won't be pinned to the sidebar anymore.</p>
+<figure>
+  <img src="/img/files-projects/04-pin-project.webp" alt="Pin project option" />
+</figure>
+
+<h3 id="move-project">Move a project</h3>
+<p>Projects can be moved between teams. To move a project, right-click on it and select <strong>Move to</strong> from the context menu. A dialog will appear showing all available teams where you can move the project. Select the destination team and confirm the move.</p>
+<figure>
+  <img src="/img/files-projects/06-move-project.webp" alt="Move project to another team" />
+</figure>
+<p>When you move a project to another team, all files within the project are moved along with it. Team members of the destination team will gain access to the project and its files according to their permissions.</p>
+<p class="advice">Moving a project to another team changes its ownership and access permissions. Make sure the destination team has the appropriate members and permissions for the work contained in the project.</p>
+
+<h3 id="delete-project">Delete a project</h3>
+<p>To delete a project, right-click on it and select <strong>Delete</strong> from the menu. You'll be asked to confirm the deletion. Keep in mind that deleting a project will also delete all files within it. Make sure you have backed up any important files before deleting a project.</p>
+<p class="advice">Deleted projects and their files are moved to the trash area where they can be restored or permanently deleted.</p>
+
+<h2 id="files-management">Files</h2>
+<p>Files are your design documents in Penpot. Each file contains pages, boards, and all the design elements you create. Files can be created within a project or in the drafts section, and you can move them between projects as needed.</p>
+
+<h3 id="create-file">Create a file</h3>
+<p>To create a new file, you have several options:</p>
+<ul>
+  <li>Click the <strong>+</strong> button in a project to create a file inside that project</li>
+  <li>Use the keyboard shortcut <kbd>+</kbd> when you have a project selected</li>
+  <li>Create a file directly in the drafts section if you're not ready to organize it into a project yet</li>
+</ul>
+<figure>
+  <img src="/img/files-projects/05-create-file.webp" alt="Create a new file" />
+</figure>
+<p>When creating a file, you'll be asked to give it a name. The file will open in the workspace where you can start designing immediately.</p>
+
+<h3 id="edit-file">Edit a file</h3>
+<p>To rename a file, right-click on the file card in the dashboard and select <strong>Rename</strong>, or click on the three-dot menu on the file card. Enter the new name and confirm the change. You can also access file settings and other options from the file's context menu.</p>
+
+<h3 id="move-file">Move a file</h3>
+<p>Files can be moved between projects, from drafts to a project, or even to projects in other teams. To move a file, right-click on the file card and select <strong>Move to</strong> from the context menu. A dialog will appear showing all available projects across your teams where you can choose the destination. Select the project where you want to move the file and confirm.</p>
+<p>You can also drag and drop files between projects in the dashboard for a quick way to reorganize your files within the same team.</p>
+<p>When moving a file to a project in another team, the file becomes accessible to members of that team according to their permissions. Moving a file doesn't affect its content or any shared libraries it might be using. Only its location in your project structure changes.</p>
+<p class="advice">When moving files between teams, be aware that this changes who has access to the file. Make sure the destination team has the appropriate members and permissions for the work contained in the file.</p>
+
+<h3 id="duplicate-file">Duplicate a file</h3>
+<p>To create a copy of an existing file, right-click on the file card and select <strong>Duplicate</strong>. The duplicated file will be created in the same location (project or drafts) with the same name plus "Copy" added to it. You can then rename or move it as needed.</p>
+<p>Duplicating a file creates a complete copy including all pages, boards, and design elements. This is useful when you want to create variations of a design or use a file as a starting point for a new project.</p>
+
+<h3 id="delete-file">Delete a file</h3>
+<p>To delete a file, right-click on the file card and select <strong>Delete</strong>. You'll be asked to confirm the deletion. The file will be moved to the trash area where it can be restored or permanently deleted later.</p>
+<p class="advice">Deleting a file doesn't immediately remove it permanently. You can recover deleted files from the trash area within a certain time period.</p>
+
+<h2 id="drafts">Drafts</h2>
+<p>The drafts section is a fixed, non-deletable space in your dashboard where you can create and store files that aren't part of any specific project yet. This is useful for quick sketches, experimental designs, or files you're not ready to organize into projects.</p>
+<figure>
+  <img src="/img/files-projects/02-drafts.webp" alt="Drafts section" />
+</figure>
+<p>Drafts appear in a dedicated section in the dashboard sidebar, separate from your projects. All team members can see and access files in the drafts section, depending on their permissions.</p>
+<p>You can create files directly in drafts, or move existing files from projects into drafts if you want to temporarily remove them from a project's organization. Files in drafts work exactly like files in projects - they have the same functionality and features.</p>
+<p>When you're ready to organize a file from drafts, you can move it into an appropriate project using the move option in the file's context menu.</p>
+
+<h2 id="trash-area">Trash area</h2>
+<p>When you delete projects or files, they are not removed permanently. Instead, they are moved to a trash area, a dedicated space for deleted content. This allows you to recover mistakenly deleted content or permanently remove items when you're sure you don't need them anymore.</p>
+<p>The trash applies to both files and projects. Items in the trash remain there for a certain period depending on your Penpot subscription plan before being automatically deleted permanently.</p>
+
+<h3 id="access-trash">Access the trash</h3>
+<p>A <strong>Trash</strong> section is accessible from the dashboard navigation. When you access it, you'll see all your deleted files and projects, each clearly labeled so you can easily identify what you want to restore or permanently delete.</p>
+<figure>
+  <img src="/img/files-projects/03-trash.webp" alt="Trash area" />
+</figure>
+
+<h3 id="trash-permissions">Trash permissions</h3>
+<p>Access to the trash and the actions you can perform depend on your role in the team:</p>
+<ul>
+  <li><strong>Owner, Admin, and Editor:</strong> Can view the trash, restore deleted items, and permanently delete items from the trash.</li>
+  <li><strong>Viewer:</strong> Cannot access the trash or manage deleted content.</li>
+</ul>
+
+<h3 id="restore-items">Restore items</h3>
+<p>To restore a deleted file or project, access the trash area and find the item you want to recover. Select the item and choose <strong>Restore</strong>. The item will be restored to its original location (the project it belonged to, or the drafts section if it wasn't in a project).</p>
+
+<h3 id="permanently-delete">Permanently delete items</h3>
+<p>If you're sure you don't need an item anymore, you can permanently delete it from the trash. Select the item and choose <strong>Permanently delete</strong>. This action cannot be undone, so make sure you really want to remove the item permanently.</p>
+<p class="advice">Items in the trash are automatically deleted after a certain period depending on your subscription plan. If you want to keep something, restore it before the auto-deletion period expires.</p>

docs/user-guide/design-systems/design-tokens.njk

@@ -455,6 +455,43 @@ ExtraBold Italic
 <p>A <strong>Typography composite token</strong> can be applied to a full text layer to set all typography properties at once. This lets you manage complete text styles using a single token instead of combining multiple individual ones.</p>
 <p>When applying a Typography composite token to a layer, any previously applied <em>Typography composite token</em> or <em>style</em> will be detached. The same happens in reverse. Only one of them can be active at a time.</p>
 
+<h3 id="design-tokens-shadow">Shadow</h3>
+<p>Shadow tokens are composite entities that encapsulate the properties of one or more shadows into a single token definition. This token can contain a single shadow or an array of multiple shadows that can be reordered.</p>
+<p>Shadow tokens support both <strong>Drop Shadow</strong> and <strong>Inner Shadow</strong> types. When creating or editing a shadow token, you can select the type of shadow you want to use. The default selection is Drop Shadow.</p>
+<figure>
+  <img src="/img/design-tokens/37-tokens-shadow-individual.webp" alt="Shadow token creation with individual values" />
+</figure>
+
+<h4 id="design-tokens-shadow-properties">Shadow properties</h4>
+<p>Each shadow within a shadow token contains a set of properties that define how the shadow appears:</p>
+<ul>
+  <li><strong>Color:</strong> The color of the shadow. Accepts the same values as <a href="#design-tokens-color">color tokens</a> (Hex, RGB, RGBA, ARGB, HSL, HSLA), and you can reference existing color tokens. The color picker is available when defining the value.</li>
+  <li><strong>X offset:</strong> The horizontal offset of the shadow. Can be unit or unitless, and accepts negative values. You can use a number or reference a <a href="#design-tokens-number">number</a> or <a href="#design-tokens-dimensions">dimension</a> token.</li>
+  <li><strong>Y offset:</strong> The vertical offset of the shadow. Can be unit or unitless, and accepts negative values. You can use a number or reference a <a href="#design-tokens-number">number</a> or <a href="#design-tokens-dimensions">dimension</a> token.</li>
+  <li><strong>Blur:</strong> The blur radius of the shadow. Can be unit or unitless. You can use a number or reference a <a href="#design-tokens-number">number</a> or <a href="#design-tokens-dimensions">dimension</a> token.</li>
+  <li><strong>Spread:</strong> The spread radius of the shadow. Can be unit or unitless. You can use a number or reference a <a href="#design-tokens-number">number</a> or <a href="#design-tokens-dimensions">dimension</a> token.</li>
+  <li><strong>Type:</strong> Whether the shadow is a drop shadow or an inner shadow. Selected via a dropdown menu, with Drop Shadow as the default.</li>
+</ul>
+<p>Each property within a shadow token can reference existing tokens or be assigned hardcoded values. Shadows can also reference other shadow tokens (the type of shadow must match when using references).</p>
+<p class="advice">Not all properties are mandatory to save a shadow token. Some can be empty (and will be computed as 0). Only the color property is mandatory. In an array of shadows, if any shadow does not have the color set, the form cannot be saved.</p>
+
+<h4 id="design-tokens-shadow-create">Creating shadow tokens</h4>
+<p>To create a shadow token, click on the <strong>+</strong> next to <strong>Shadow</strong> in the Tokens panel. Shadow tokens can be created in two ways:</p>
+<ul>
+  <li><strong>Individual values:</strong> You can create one shadow or multiple shadows with individual property values. Click the <strong>+</strong> button to add more shadows to the array. New shadows are added at the top of the list.</li>
+  <li><strong>Single reference:</strong> You can reference another existing shadow token. When using a single reference, you cannot add more than one shadow. The resolved value will display the shadow or list of shadows that the referenced token contains.</li>
+</ul>
+<figure>
+  <img src="/img/design-tokens/38-tokens-shadow-reference.webp" alt="Shadow token creation with reference" />
+</figure>
+<p>When creating a shadow with individual values, the color value starts empty, but the other inputs have default values (X: 4, Y: 4, Blur: 4, Spread: 0). You can reorder shadows by hovering over a shadow form and using the reorder button to drag it to a different position.</p>
+<p>You can also reference another existing shadow token instead of defining each property manually. When doing so, Penpot resolves all shadow properties from the referenced token.</p>
+
+<h4 id="design-tokens-shadow-apply">Applying shadow tokens</h4>
+<p>Shadow tokens can be applied to any layer type. Clicking on a shadow token will apply it to the selected layer. Right-clicking on a shadow token shows the context menu with the <strong>Shadow</strong> option to apply it.</p>
+<p class="advice">Text elements in CSS do not support inner shadows, but Penpot does, since it uses the filter property internally instead of the box-shadow property.</p>
+<p>When applying a shadow token, any existing shadow on the layer will be overridden (whether it's a raw shadow or an applied token shadow). If the token contains an array of shadows, each shadow will be added in the same order as in the creation form.</p>
+<p class="advice">In Penpot, an element can have multiple shadows, but only one token of the same type can be applied. This means that applying a second shadow token would override the first one, regardless of how many shadows the shape currently has.</p>
 
 
 

frontend/translations/en.po

@@ -7551,6 +7551,10 @@ msgstr "Remap Token References"
 msgid "workspace.tokens.renaming-token-from-to"
 msgstr "Renaming token from '%s' to '%s'"
 
+#: src/app/main/ui/workspace/tokens/management/forms/generic_form.cljs
+msgid "workspace.tokens.warning-name-change"
+msgstr "Renaming this token will break any reference to its old name"
+
 #: src/app/main/ui/workspace/tokens/remapping_modal.cljs
 msgid "workspace.tokens.references-found"
 msgstr "%s references found in your design"

frontend/translations/es.po

@@ -4428,6 +4428,10 @@ msgstr "Actualizar referencias de token"
 msgid "workspace.tokens.renaming-token-from-to"
 msgstr "Renombrando el token de '%s' a '%s'"
 
+#: src/app/main/ui/workspace/tokens/management/forms/generic_form.cljs
+msgid "workspace.tokens.warning-name-change"
+msgstr "Cambiar el nombre de este token romperá cualquier referencia a su nombre anterior."
+
 #: src/app/main/ui/workspace/tokens/remapping_modal.cljs
 msgid "workspace.tokens.references-found"
 msgstr "%s referencias encontradas en tu diseño"