design-system

Design System — a system made from the shared type

This artifact is one release of the Design System runtime: index.html, this SKILL.md and artifact-type/. A design system is an ordinary artifact that serves them read-only and keeps its content in ITS OWN FILES under project/; icons and images sit in its asset store, named by the index. A system inherits the type's capabilities
{"artifact":{},"downloads":{},"user":{"scopes":["profile"]},"assets":{},"comments":{"composer_only":true,"customAnchors":true},"room":{},"db":{"rules":[{"path":"","write":"admin"}]}}
and contract "0.2.47". Writes need Can edit; a session without it says so, no retries.

Write only under project/: everything else is the type's (refused).

A system kept in files

Its index is project/design-system.json, nothing else, holding a createdOnFiles or convertedFrom object, the marker (read it first; no project/design-system.json: an empty system, see Creating; for a clean-up, stop and say so):
{"v":3, "layout":"files", "createdOnFiles":{"v":1,"at":"2026-09-14T18:20:00Z"}, "title":"Acme", "namespace":"Acme", "libraries":[{"name":"react","version":"18"},{"name":"react-dom","version":"18"}], "sections":{}, "groups":["Logos","Icons"], "assetGroups":{"Logos":{"name":"Logos","tile":"l","order":[],"files":{}}}, "blobs":{}, "docs":{"readme":"project/README.md","sections":[]}}.
"editing": "off" in the index turns off editing on the page; it, or a source entry not marked upgraded, has the page offer a clean-up ("Finish the migration"). Asked for one in words, not by its button, first ask if they want its files reorganized into this format. Then do so by Revising. Files the format has no place for (kits, some foundations pages) stay put. Keep authors' words; add nothing in their voice. Pictures, fonts and scripts stay files, moved where format.md puts them, paths repaired: upload none, inline none, whatever else these pages say. Remove files only as (craft.md: Move aside) says; name any you could not. Remove editing and source in the LAST call, once files follow format.md. Other changes are just made, both kept.
Everything under assets/<Group>/ that is not text (icons, logos, images, SVG too, video, PDF) is an asset upload, named by a record assetGroups.<Group>.files.<file>: {"name", "blob": "<id>", "size", "type"}: name = its path below the group folder (acme-mark.svg), the key the same with bytes outside [A-Za-z0-9_./-] written ~ + two hex; <id> from the /_blob/<id> the upload returned; size in bytes; type its media type. A group's order lists those names in tile order; groups orders the groups. Leave sections, blobs and docs to the page (new index: {}, {}, {"sections":[]}). To revise: ONE publish whose files holds only the project/ paths you changed; no capabilities, contract. The index goes ONCE, in the LAST call of your work, never in the small calls before it (a call replaces the whole file: a copy read earlier would undo a rename, or drop the record of an icon a person added meanwhile): read it right before, change those (its lastChange and the keys your change touches: title, libraries, an asset record), keep every other key and the marker. A system YOU start (no index yet) gets project/design-system.json with createdOnFiles exactly so, at = now. A project/design-system.json with no marker is not an index: the page opens read-only; say so, write nothing over it.