> ## Documentation Index > Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt > Use this file to discover all available pages before exploring further. # Artifacts library > Find, preview and open your artifacts in one place, then use versions, restore and history for projects, dashboards, slides and designs. The Artifacts library at `/artifacts` lists everything people and agents made in a workspace: projects, dashboards, Pages with panels, Word documents, sheets, slide decks and designs. From the library you can search and filter artifacts, preview one without leaving the list, and open it to see its content, versions and history. > [!NOTE] > > The library is off by default. Each part of it is switched on separately: > > | What | Needs | > | - | - | > | The library at `/artifacts`, and the sidebar **Artifacts** link pointing to it | build-time `NEXT_PUBLIC_ARTIFACTS_LIBRARY=true` | > | Projects: the project viewer, versions, history and restore | build-time `NEXT_PUBLIC_CHAT_ARTIFACT_PROJECTS=true`, and the workspace flag `artifact_projects` (on by default, unless a manager turned it off; `CREWSHIP_ARTIFACT_PROJECTS_ENABLED=true` forces it on) | > | Dashboards in the viewer, and creating one | the project switches above, plus build-time `NEXT_PUBLIC_ARTIFACT_DASHBOARDS=true`, and the workspace flag `artifact_dashboard_data` (or `CREWSHIP_ARTIFACT_DASHBOARD_DATA_ENABLED=true`). Without the server switch, a dashboard is listed as a Project. | > | Slide decks in the viewer, and creating one | the project switches above, plus build-time `NEXT_PUBLIC_ARTIFACT_SLIDES=true`, and the workspace flag `artifact_slides` (or `CREWSHIP_ARTIFACT_SLIDES_ENABLED=true`). Without the server switch, a slide deck is listed as a Project. | > | Designs: listing, creating and the canvas | build-time `NEXT_PUBLIC_ARTIFACTS_DESIGN=true`, and the workspace flag `artifacts_design` (or `CREWSHIP_ARTIFACTS_DESIGN_ENABLED=true`) | > | The Craft lease bar for Word in the detail view | build-time `NEXT_PUBLIC_CHAT_CRAFT_LEASE=true` | > > The default production build sets none of these to `true`. Enable a workspace > flag with `crewship feature-flag enable `; see > [feature-flag](https://docs.crewship.ai/cli/feature-flag.md). With `NEXT_PUBLIC_ARTIFACTS_LIBRARY` > unset, `/artifacts` sends you to `/pages`. `NEXT_PUBLIC_ARTIFACTS_DESIGN=true` > on its own also serves `/artifacts`. ## Artifact kinds Each artifact holds one kind of content. The kind decides what opens it and whether it has versions. The library groups kinds as **Artifacts** (many people at once) and **Craft** (one editor at a time). | Kind | Family | What it is | Versions | Made by | | - | - | - | - | - | | Docs | Artifact | A shared document or canvas (board) | Yes | You, as a blank document, or an agent from chat | | Dashboard | Artifact | Numbers and tables agents keep current, or a Page with panels (monitors and queues that crews fill, see [Pages](https://docs.crewship.ai/guides/pages.md)) | Projects: yes. Pages with panels: no | An agent from chat, or you as an empty Page with panels | | Slides | Artifact | A deck you can present | Yes | An agent, from chat | | Design | Artifact | A shared canvas with screens; a design system shows as **Design · Library** | Yes | You, as a blank canvas | | App | Artifact | HTML you can run. **App · Static** is a multi-file HTML project; an App with an application, or a project that runs its own scripts (an interactive app, such as the Crewship Showcase), runs it. An interactive app is an App even when it keeps data in a collection | Yes | An agent from chat | | Word | Craft | A document that one person edits at a time | Yes (native documents) | You, or an agent from chat | | Sheet | Craft | A workbook with formulas | Yes (native workbooks) | Listed in the library. You can't create one here yet. | A Page with panels (monitors and queues that crews fill, see [Pages](https://docs.crewship.ai/guides/pages.md)) shows as a **Dashboard**, or as an **App** when it publishes an application. The card, the **Kind** chips on Home, the **Kind** filter in the side panel, its counts, the **Preview** panel and the artifact's own header all use the same kind. The library knows a design system and an interactive app from the list itself, before you open them, so a design system is counted under **Designs** and an interactive app under **Apps** everywhere. Older searches and links keep working: `kind:project` finds Apps, `kind:page` finds the kind a Page with panels shows as. Each item in the library shows its version state: * **Shared vN**: people with access see version N. * **Not shared**: the artifact has versions, but none is shared yet. * No chip: the kind has no versions, such as an App made from a Page with panels. Other chips mark an item as **Private**, **Empty**, **Test** or **Archived**. ## Open the library 1. In the sidebar, under **Work**, click **Artifacts**. 2. The library opens on **Home**: * **Needs attention** lists up to six artifacts that need you, by one fixed rule (below). It is hidden when nothing does. * Below it, every artifact in view (all of them, or the folder you picked) as a **Grid** of cards or a **Table**. Kind chips above the list (**All**, **Docs**, **Apps**, **Word** and so on, each with a count) narrow it to one kind. 3. On the left, the side panel has a search box, a **Filter** button, the main lists (**Home**, **All artifacts**, **Needs attention**, **Recently opened**), then **Views** and **Folders**. ### The Needs attention rule An artifact needs attention when one of these is true, checked in this order: 1. **Your recovered draft**: this browser kept unsaved edits to a native Word document after its edit lock was lost. Only you see it, and only in this browser. 2. **Refresh failed**: at least one of its panels failed to refresh and keeps its last confirmed data. 3. **Data is stale**: at least one panel is past its refresh window, and you own the artifact. Archived and test-made items never need attention. "Not shared yet" is not a reason. The list shows drafts first, then failed refreshes, then stale data, newest first within each, and stops at six. A proposal waiting for review or another person holding the edit lock shows in the open artifact's status chip instead. The rule lives in `components/features/artifacts-library/attention.ts`. An empty workspace shows **No artifacts yet** with a **New artifact** button. If the workspace holds only blank items, the message says how many are in **Empty** and offers **Show empty**. ## Find an artifact ### Search Type in **Search artifacts…** at the top of the side panel. Text matches the name or the address (slug). You can also use these operators: | Operator | Matches | | - | - | | `kind:app`, `kind:dashboard`, `kind:design`, `kind:word`, `kind:slides`, … | That kind; the plural form also works | | `is:shared` | Artifacts with a shared version | | `is:unshared` or `is:draft` | Artifacts with versions but no shared version | | `is:private` | Artifacts only their owner can open | | `is:empty` | Artifacts with nothing in them yet | | `owner:you` | Artifacts whose owner name contains the text, ignoring case: `you` for your own, or part of a crew name | For example, `kind:dashboard is:shared sales` finds shared dashboards whose name contains "sales". If you search from **Home**, the library switches to **All artifacts**. ### Filter 1. Click **Filter** next to the search box. 2. A block opens with the groups **Kind**, **Who can open**, **Version** and **Owner**. They start folded; click a group's heading to expand it. 3. Pick values: **Who can open** has **Everyone with access** and **Private**, **Version** has **Shared version**, **Not shared yet** and **No versions**. The count next to each value is how many items you would see if you picked it. **Kind** and **Version** values with no matching artifact are hidden unless you already selected them. **Clear** in the block's header drops all filters. 4. To close the block, press Esc or click **Filter** again. Chips under the main lists show the filters you set; click a chip's remove button to drop that filter. ### Views and folders **Views** in the side panel: * **Mine**: artifacts you own. * **Favorites**: artifacts you starred. * **Clean up**: names that repeat with a number or date, such as "Smoke test 1", "Smoke test 2", "Smoke test 3". It only suggests what to tidy up. * **Test items**: artifacts the server marks as made by tests or probes. * **Empty**: artifacts with nothing in them yet. * **Archive**: archived artifacts. Empty, test and archived items appear only in their own view, never in **All artifacts**, **Mine** or **Favorites**. One exception: a blank item you created yourself with **New artifact**, such as a new **Page with panels**, stays in **All artifacts**, **Mine** and search, so you can find it again before crews fill it. It also stays in **Empty**. **Clean up**, **Test items**, **Empty** and **Archive** appear in the panel only when they hold something. Nothing in these views is deleted. **Folders** lists your folders with their item counts, and **Unfiled** for artifacts in no folder. Click a folder to list only what it holds; click it again to leave it. ### Sort, group and layout Above the list: * **Sort**: **Last edited** (the default), **Name** or **Kind**. * **Group**: **None**, **Kind** or **Folder**. * Layout: **List**, **Gallery** or **Table**. **Table** has the columns **Name**, **Kind**, **Shared**, **Folder** and **Updated**. The view, search and filters are kept in the address (`view`, `q`, `kind`, `access`, `version`, `owner`, `folder`). A reload keeps them, and you can send the link to someone. ## Preview and open an artifact On a desktop, a click previews an artifact without leaving the list: 1. Click an artifact. A **Preview** panel opens on the right with its kind, version, folder, who can open it, owner and when it was last edited. It also has **Open** and **Share** buttons and a star. 2. To open the artifact, click **Open** or press Enter. In a wide window, where the preview sits beside the list, clicking the same row again also opens it. In a narrower window the preview covers part of the list, and a click outside it closes the preview instead. 3. To close the preview, press Esc or click the close button. To move through the list from the keyboard, press J for the next item and K for the previous one; the preview follows. On a phone, a tap opens the artifact directly. An open artifact has its own address, `/artifacts/`, where `` is the artifact's permanent ID. Links in the older forms `/artifacts?item=`, `/artifacts/` and `/artifacts/@` still work and move to the ID address. To go back to the list, click **All artifacts** or press Esc. ### What the detail view shows Every kind opens in the same frame. The folder panel steps aside while an artifact is open; the pin button at the top of the panel keeps it open beside every artifact. * **The header** reads `Artifacts › folder › name`. Click the folder (or **All artifacts**) to go back. The name opens the **artifact menu**, which holds every action: **Share…**, **Copy link**, **Move to folder…**, **Add to favorites**, **Version history** where the kind has one, and **Info**. An action you can't use stays in the menu, greyed out, with the reason under it. * **The status chip** beside the name says what is happening, for example **Saving…**, **Saved · v4**, **Jana is editing**, **Read-only** or **Stale · 1 panel**. Click it for details. **Saved** appears only after the server confirms the version. A kind with no live signal shows no chip. * **The right side of the header** has **Agent**, **Comments** and **History** (each where the kind supports it) and **Share**. * **The drawer** on the right holds the kind's own tabs plus **Agent**, **Comments**, **History** and **Info**. **Info** shows the kind, version, owner, folder, link and who can open the artifact and why. On a tablet the drawer covers the right side; on a phone it fills the screen. * **Agent** offers only what the server supports for that kind. **Ask** opens chat with the artifact as context and your request as an unsent draft. **Edit** appears for a native Word or Sheet when the server allows agent tasks and you can edit; it starts the Craft agent task. With no agent path at all, there is no **Agent** button. On a phone the header shows only the back button, the name and the status chip, with **Agent**, **Comments** and **⋯** (the artifact menu). The body depends on the kind: * **Project**, **Dashboard**, **Slides**: the artifact viewer, with the tabs **Preview**, **History** and **Comments** and a version switch in its header. See [Versions](#versions). * **Design**: the design canvas. * **Page**: the Page's panels, shown in the detail view. * **Native Word and Sheet**, with `NEXT_PUBLIC_ARTIFACTS_LIBRARY` enabled: the Craft editor opens inside the detail when the server confirms editing is available. Readers without edit access get the shared preview. This mode has no full-view link; `/pages/` leads back to the artifact detail. Version history opens in the drawer. * **Word** outside that mode: a read-only preview of the saved version, with **Open full view**. When the Craft lease bar is enabled, it shows who holds the lease and offers **Edit** in a new tab. * **Sheet** outside that mode, and project kinds whose viewer is switched off: the name, kind and state, with **Open full view**. If an address does not open, the frame says what the server answered: **Sign in to open this artifact**, **You don’t have access** or **This artifact doesn’t exist**, each with **Back to Artifacts**. Nothing of the artifact is shown behind these pages. If the server gives no clear answer, the library shows **This artifact is not available.** ## Create an artifact 1. **New artifact** in the top bar is a split button: * The main part starts the kind you last started from this button, its menu or the Home guide (the first kind you can make the first time). Press **N** in the library list for the same; it does nothing while you type or while a dialog is open. * The arrow (or **Shift+N**) opens the menu. **Pinned** lists up to five kinds; press **1**–**5** to start one. **Recent** lists up to three kinds you started lately that aren't pinned. **All kinds** shows every kind, grouped **Artifacts** and **Craft**, with a **Family** filter. **Find a kind** searches names, editors (WordCraft, GridCraft) and file types (`.docx`, `.xlsx`, `.csv`); **Enter** starts the first result. A kind this workspace can't create shows **Off**. * Click the star next to a kind to pin or unpin it. **Edit** reorders the pins and **Reset to default** brings back the first five kinds. A sixth pin is refused with **Pinned is full (5)**. * Pins, recent kinds and the Home guide are your own preferences: they follow you across devices and are kept per workspace (the guide once for all). Nobody else sees them. Home shows the guide **Two kinds of things live here** until you click **Got it**; **Show the guide on Home** in the menu brings it back. Pick a kind there or **Browse** one family in the menu. **App** starts a project. 2. In the **New artifact** dialog you can still change the kind. Kinds that this workspace can't create are listed under **Coming**. **Docs** is offered when the server confirms the shared document format; **Word** when it confirms a Word editor (native Word `wordcraft_native`, the WordCraft SDK or commands); **Sheet** when it confirms native Sheet (`gridcraft_native`). A workspace that serves only the shared document format offers **Docs**, not **Word**: that document opens as Docs. 3. Enter a **Name**. Pick a **Folder**, or leave it **Unfiled**. If an artifact of the same kind and name is already in that folder, a warning offers **Open it** instead. 4. Under **Start with**, choose how to start: * **Page with panels**: **Empty page**. Click **Create page**. Crews add panels on their next run. * **Design**: **Blank canvas**. Click **Create and edit**. * **Docs**: **Blank**. Click **Create and edit**. The document opens at its own address and is listed under **Docs**. It is yours until you share it; then others with access write in it at the same time. * **Word**: **Blank** to open an empty document with you holding the lease, or **Describe it** to have an agent write the first draft. For **Describe it**, chat opens with your request as a draft; turn on **Create document** in chat, then send it. * **Project**, **Dashboard**, **Slide deck**: **Describe it** or **From template**. Click **Continue in chat**. Chat opens with your request as a draft. Turn on **Create artifact project** in chat, then send it to an agent. Without it, the message goes out as a plain chat message and no artifact is made. The agent creates the artifact unfiled; you can file it afterwards. A new artifact starts as **Only you until you share it**. If you picked a folder, it starts as **People with access to** that folder. Who can create: an Owner, Admin or Manager, or a member with the `page.create` capability. The server checks this on every create. A member who can't create, such as a Viewer, doesn't see **New artifact** in the bar or in the empty library; this includes Project, Dashboard and Slide deck, which an agent makes for you. ## Versions Projects, dashboards, slide decks and designs keep immutable, numbered versions (v1, v2, …), and so do native Word documents and sheets. Each save by an agent or a person adds a new version. Two versions matter most: * **Latest**: the newest version. Its owner, and people with edit access, work on it. * **Shared**: the version other readers see. Until a version is shared, the artifact is a **Draft** and readers see nothing. For projects, dashboards and slide decks, what you can see depends on your access: | Who | Sees | | - | - | | The owner | Every version and the full history, and can share and restore | | A person with edit access | The latest version | | Anyone else with access | Only the shared version | The steps below use the project viewer. Projects, dashboards and slide decks open in it. ### View an older version 1. Open the artifact. The viewer header shows the version switch: **Latest v3** and **Shared v2**, for example. If nothing is shared, **Shared** shows **—** and can't be selected. 2. Click **Shared** to see the version readers get. A banner says **You see the shared version v2, the one people with the link get.** and names the latest version. 3. For any other version, open the **History** tab and click **View** next to it. A banner says **You are viewing v1. Latest is v3.**; click **Back to latest** to return. You can't comment on an older version; comments go on the latest one. ### Share a version 1. Open the artifact and show the version you want to share. It is usually **Latest**. 2. In the toolbar under the tabs, click **Share** (the link icon, not the **Share** button in the top row). 3. The popover says **People with access will see v3. Later versions stay private until you share them.** Click **Share v3**. 4. **Shared v3** appears, and the header chip changes from **Draft** to **Shared**. Only the owner can share a version. The top-row **Share** button controls who has access, not which version they see. ### Restore an older version Restoring never rewrites history. It copies an older version into a new version on top. 1. Open the artifact and click the **History** tab. The list says, for example, **3 versions · restore makes a new version, nothing is deleted**. Each row shows the version number, who saved it, its message and when, with **Latest** and **Shared** marked. 2. Next to the version you want back, click **Restore as new version**. 3. A notice says **Restored v1 as v4 · nothing deleted**. The new version's message is **Restore version 1**, and its row says **Restored from v1**. 4. The shared version does not change. To show the restored content to readers, share the new version. Only the owner can restore. If someone saved a newer version while you were looking, the restore is refused and a banner says **Someone saved a newer version while you were working. Nothing was overwritten.** Reload, then try again. ## History and storage limits The history of each project, dashboard, slide deck and design has its own storage budget. The server configures history limits for native Word documents and sheets separately. | Limit | Value | | - | - | | History per artifact (all versions together) | 256 MiB | | One version | 32 MiB | | Files in one version | 256 | | Warning | at 80% of the history budget | Files with identical content are stored once per artifact. Restoring an older version therefore takes up almost no new space. The history is kept in full (`keep-all`): nothing is pruned or deleted automatically. A person with edit access works on the latest version only (`latest-version-only`). A reader who only sees the shared version gets that one version (`shared-version-only`), never the older ones. When a project's history passes 80%, the owner sees a banner in the viewer, **This project is close to its limit**. It shows how much is used, for example **205 MB of 256 MB (80%)**, with a **Review versions** button that opens **History**. When a save would go over a limit, it is refused with HTTP 413, and the viewer shows **Saving is paused**: **History is full, so this was not saved.** Existing versions stay intact, and your draft comment stays in place. A version with more than 256 files is refused as invalid. ## Favorites and recently opened * To star an artifact, click the star in the preview or in the detail view (**Add to favorites**). Click it again to remove it. * **Favorites** lists your starred artifacts. **Recently opened** lists the last ones you opened, newest first. Both lists are personal. They follow you to other devices and nobody else sees them. **Favorites** and **Recently opened** leave out empty, test and archived items, except a blank item you created yourself. ## Troubleshooting | You see | Why | What to do | | - | - | - | | **Artifacts** in the sidebar opens `/pages` | The build was made without `NEXT_PUBLIC_ARTIFACTS_LIBRARY=true` | Rebuild the web app with the flag | | A project shows only its name and **Open full view** | The project viewer is off: `NEXT_PUBLIC_CHAT_ARTIFACT_PROJECTS` is not `true`, or the server reports projects unavailable for this workspace | Set the build flag; if `artifact_projects` was turned off, run `crewship feature-flag inherit artifact_projects` (or `enable`) | | The **New artifact** menu lacks a kind | That kind's build flag or workspace switch is off, or you can't create artifacts | See the table at the top of this page | | **This artifact isn't available** | The artifact was archived, or you are not allowed to see that version | Ask the owner to share it with you | | **Saving is paused** | The history or a single version reached its limit | Ask an agent to make the artifact smaller, or save a copy | ## Related * [Pages](https://docs.crewship.ai/guides/pages.md): panel Pages that crews keep filled * [Docs history and compare](https://docs.crewship.ai/guides/document-history-review.md): history for the separate Docs backend * [Native Word and Sheet editing](https://docs.crewship.ai/guides/artifacts/word-and-sheet.md): Craft custody, confirmed saves and recovery * [feature-flag](https://docs.crewship.ai/cli/feature-flag.md): enable workspace flags ## Publish a Library and pin it in other projects A Design System artifact is the Library. Saving a version does not change any other project: the Library's **owner** chooses the published version with `crewship page artifact library publish --version `. Editors keep saving draft versions; they do not publish. A project that uses the Library keeps its own copy of the published `design-system.json`, made with `crewship page artifact pin set`. The copy is a record the project owns: * restoring or editing the Library never changes it; * deleting the Library, or losing your access to it, keeps the copy; * losing access does block the next update; * everyone who can read the project can read the copy (tokens, Library name, and the font and licence files the pin carries), even without access to the Library, and the copy survives unsharing the Library. Pin only what all of the project's readers may see. ### What a pin carries Tokens are closed literals (hex colours, pixels, plain font-family names), so they cannot reference other files. Besides `design-system.json`, a pin carries the Library's **font files** and the **licence files** that let them travel: * Store a font in the Library as a text file with a font extension (`.woff2`, `.woff`, `.ttf`, `.otf`) whose content is a base64 data URL, for example `data:font/woff2;base64,d09GMg…`. The bytes must start like the format the extension names. * An optional `fonts.json` names each font's family, weight and style, and may give its licence as an SPDX id: ```json theme={null} {"schema_version": 1, "fonts": [ {"file": "fonts/Inter-Regular.woff2", "family": "Inter", "weight": 400, "style": "normal"}, {"file": "fonts/Brand.woff2", "family": "Brand", "license": "LicenseRef-Proprietary"} ]} ``` * A font is copied only with a redistributable licence: * an explicit `license` in `fonts.json` of `OFL-1.1`, `OFL-1.0`, `Apache-2.0`, `MIT`, `UFL-1.0`, `CC0-1.0`, `Bitstream-Vera` or `BSD-3-Clause` (any other id keeps the font out, whatever licence files say); * without one, a `LICENSE`, `OFL` or `COPYING` file **next to the font** titled with the SIL Open Font License 1.1, Apache License 2.0, the Ubuntu Font Licence 1.0, the MIT License or CC0 1.0 Universal; * without either, a licence file at the **Library root** only when it is a font licence (OFL or UFL). A root MIT or Apache `LICENSE` usually covers the repository's code, so it never lets an undeclared font travel; declare the font's `license` in `fonts.json` instead. Only the licence's title line counts (for example `SIL OPEN FONT LICENSE Version 1.1`), at the start of a line; a sentence that merely mentions a licence, such as "not under the SIL Open Font License", does not. The licence file is copied with the font. * A font without such a licence, over 1 MiB, or one that would take the pin past 4 MiB is listed with the reason and never copied. The 4 MiB covers every copied byte, the licence files included. Nothing is ever downloaded. Publishing refuses a version whose `fonts.json` or font files are invalid. `crewship page artifact pin files ` returns the carried files, bytes in base64; each copy is checked against its SHA-256 whenever its bytes are read. The pin itself, `pin show` and `pin check` list the files without loading the bytes. The project's Library notice lists the fonts its pin left behind, with the reason. A pin made before fonts travelled with a Library holds the published version but no files. `pin check` then reports `dependencies_missing` together with `update_available`, and applying the same version copies the fonts without changing the tokens. ### Previews render from the pin A project that pins a Library previews with its own copy, never the live Library, so edits, restores and publications change nothing until someone applies an update: * a static project preview gets the pinned default theme as CSS custom properties, first in its `` so the project's own styles still win: `--ds-color-`, `--ds-space-`, `--ds-radius-`, `--ds-font-` and `--ds-font-size-`, plus an `@font-face` for each copied font that `fonts.json` names. Use them as `color: var(--ds-color-primary)`; * Slides can name pin tokens in an optional `slides-library.json` file in the consumer's saved project. For example: `{"schema_version":1,"background":"canvas","text_color":"ink","typography":"body"}`. The first two names select color tokens; the third selects the text size, weight and font family. The preview, thumbnails and Present use the resolved values. A missing token or uncopied font keeps the saved styling for that property. The PDF still uses the saved deck. Interactive and Dashboard previews do not apply the pinned theme yet. When the owner publishes a different version, `crewship page artifact pin check` reports **update available** with the token paths it adds, removes and changes, the font and licence files it adds, removes and changes, and the fonts it would leave behind with the reason. Nothing changes until someone with Edit on the project applies exactly the reviewed state with `pin set --version --if-pinned-library --if-pinned-version `. Workspace administrators cannot pin a Library they reach only through their administrator role. Full reference: [CLI: Library publication and pins](https://docs.crewship.ai/cli/artifacts.md#library-publication-and-pins). ## Design System token preview A Design System is a Project artifact whose version includes a file named `design-system.json`. It uses the same versions, access rules and sharing as Projects. It is separate from the collaborative Design canvas and does not apply tokens to another artifact automatically. The read-only preview needs `NEXT_PUBLIC_ARTIFACT_DESIGN_SYSTEM=true` in the web build, plus the Project server flag and a library or chat viewer enabled as described above. For example, build from source with: ```bash theme={null} NEXT_PUBLIC_ARTIFACTS_LIBRARY=true NEXT_PUBLIC_CHAT_ARTIFACT_PROJECTS=true NEXT_PUBLIC_ARTIFACT_DESIGN_SYSTEM=true make build ``` 1. Ask an authorized agent to create a Project containing `index.html` and the token file, or supply those files through `crewship page artifact create`. 2. Open the artifact in the library. The viewer badge reads **Design System**. It displays color swatches, typography samples, spacing and radius samples, and optional component names and descriptions. With the Library view (Design · Library), a system with more than one theme shows a theme switch beside the search box: each swatch and each component preview then uses that theme's values. Every swatch shows the contrast ratio of white or black text on it (whichever is higher) and its WCAG 2 level (**AAA**, **AA**, **AA large** or **Low**), plus the colour's usage note and, when the system has more than one theme, its value in every theme. The chat artifact pane lists every theme's value and usage note too. Text styles are grouped when the file names groups. **Files** in the section list shows every file of the shown version with its path, type and size. **View** shows a file as plain text (the first 64 KiB of UTF-8 text; nothing is rendered or run) and **Download** saves it under its own name. The Library shows colors, typography, spacing, corner radius, components, the README and component previews; it has no shadows or assets section, so such files appear only under **Files**. 3. Use the version picker to inspect retained token values you may read. The owner can restore an old version as a new version and share it separately. The preview has no token editor; publish a complete manifest to change it. A minimal `design-system.json` is: ```json theme={null} { "schema_version": 1, "name": "Harbor", "colors": {"primary": "#1d4ed8"}, "typography": {"body": {"size": 16, "weight": 400}}, "spacing": {"md": 16}, "radii": {"sm": 4}, "components": [{"name": "Button", "description": "Primary action"}] } ``` ### Themes (schema 2) Schema 2 adds themes. A schema 1 file keeps working exactly as before; nothing converts it, and its download is the file as stored. ```json theme={null} { "schema_version": 2, "name": "Harbor", "themes": [{"id": "light", "name": "Light"}, {"id": "dark", "name": "Dark"}], "colors": { "surface": {"value": {"light": "#f4f1ea", "dark": "#0b1726"}, "usage": "Page background."}, "ink": {"value": {"light": "#0f1f33", "dark": "{surface}"}}, "accent": "#e8833a" }, "typography": {"body": {"size": 15, "weight": 400, "group": "Text"}}, "spacing": {"md": 16}, "radii": {"sm": 4} } ``` * `themes` is required in schema 2: 1 to 8 entries with a unique `id` (a token name) and a `name` of at most 40 characters. The first theme is the default. * A colour is a hex value (the same in every theme), an alias such as `"{surface}"`, or `{"value": {: hex or alias}, "usage": …}`. The value must name the first theme; a theme it leaves out takes the first theme's value. Naming a theme that `themes` does not declare rejects the file. * An alias names another colour and resolves in each theme separately, up to 16 steps. An alias to a missing colour, or a cycle, rejects the file. * `usage` is plain text of at most 280 characters. * A text style may have a `group` of at most 40 characters. * Aliases, `usage`, `themes` and `group` are rejected in a schema 1 file. A file with a `schema_version` newer than this version of Crewship reads shows **This Design System uses format version N, which this version of Crewship cannot show. The file is unchanged.** instead of a partial view. ### Limits The file must be at most 32 KiB and have exactly one entry in the manifest. `schema_version`, `colors`, `typography`, `spacing` and `radii` are required; `name` and `components` are optional. Unknown fields or duplicate JSON keys reject the whole preview. Each token group permits at most 128 entries. Token names start with a lowercase letter and contain only lowercase letters, digits and hyphens, at most 48 characters; `constructor` and `prototype` are reserved. Colors are literal six-digit hex values. Spacing and radii are integer pixels from 0 to 4096. Typography requires integer `size` from 1 to 512 and optionally `font_family` (a plain font-family list), `weight` (100–900 in steps of 100), and `line_height` (0.5–4). The optional component list holds at most 64 uniquely named entries with plain-text names up to 80 characters and descriptions up to 280. Tokens cannot contain CSS expressions, markup or URLs. An invalid file shows **This Design System file is invalid or uses an unsupported format.** Saving a Project does not validate this preview format: correct the token file and publish a new complete version. With the preview flag off it remains a normal Project. A Slides manifest takes precedence over the Design System preview; keep these formats in separate artifacts. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.