{"protocol":"clank-doc/1","frameworkVersion":"0.13.0","slug":"design-system","title":"Design system and component workshop","description":"Clank Design Studio at design.clank.run is the canonical interactive workshop for the framework's dependency free headless UI. It renders all 37 component families with their real Clank controllers, lets you compare ten complete themes, and","group":{"id":"framework","title":"Framework"},"url":"https://docs.clank.run/docs/design-system","source":"docs/design-system.md","headings":["Open the workshop","Theme package","Apply a preset","Define a custom theme","Use the Design Studio MCP server","Build and verify locally"],"tableOfContents":[{"id":"open-the-workshop","title":"Open the workshop","level":2},{"id":"theme-package","title":"Theme package","level":2},{"id":"apply-a-preset","title":"Apply a preset","level":2},{"id":"define-a-custom-theme","title":"Define a custom theme","level":2},{"id":"use-the-design-studio-mcp-server","title":"Use the Design Studio MCP server","level":2},{"id":"build-and-verify-locally","title":"Build and verify locally","level":2}],"markdown":"# Design system and component workshop\n\nClank Design Studio at [design.clank.run](https://design.clank.run) is the canonical interactive\nworkshop for the framework's dependency-free headless UI. It renders all 37 component families\nwith their real Clank controllers, lets you compare ten complete themes, and exposes the same\ncontracts to people and agents through HTML, JSON, and MCP.\n\nThe studio is itself a Clank application. It is server rendered, hydrated in place, responsive,\ndeployed through the Clank control plane, and has no package dependencies. That makes it both a\nreference and a continuously exercised integration test for the framework.\n\n## Open the workshop\n\n- [Component overview](https://design.clank.run)\n- [Theme laboratory](https://design.clank.run/themes)\n- Component specimens use `https://design.clank.run/components/<slug>`.\n- The structured component catalog is [design.clank.run/api/catalog.json](https://design.clank.run/api/catalog.json).\n- The structured theme catalog is [design.clank.run/api/themes.json](https://design.clank.run/api/themes.json).\n- Agent discovery begins at [design.clank.run/.well-known/clank](https://design.clank.run/.well-known/clank).\n\nEach component page includes a live specimen, responsive preview widths, optional grid and anatomy\noutlines, the canonical semantic parts, a focused package import, upstream anatomy reference, and\nthe factory metadata an agent needs to generate the component correctly.\n\n## Theme package\n\nImport the visual token layer separately from the unstyled controllers:\n\n```ts\nimport {\n  CLANK_THEME_PRESETS,\n  applyClankTheme,\n  createClankThemeStylesheet,\n  defineClankTheme,\n} from \"@clank.run/framework/ui/theme\";\n```\n\n`CLANK_THEME_PRESETS` contains ten immutable themes:\n\n| Theme | Scheme | Character |\n| --- | --- | --- |\n| Clank | Dark | High-contrast workshop with electric green. |\n| Porcelain | Light | Precise blue product UI with crisp geometry. |\n| Midnight | Dark | Deep navy observability surfaces and cyan signals. |\n| Sakura | Light | Editorial pink and plum with generous curves. |\n| Terminal | Dark | Dense monospace controls, square edges, and zero motion. |\n| Tangerine | Light | Warm commerce surfaces with saturated orange. |\n| Nordic | Light | Cool paper whites, teal, and restrained density. |\n| Grape | Dark | Aubergine panels and dramatic ultraviolet curves. |\n| Sandstone | Light | Architectural neutrals, rust, and hairline geometry. |\n| Candy | Light | Playful pink and violet with large friendly controls. |\n\nEvery preset implements the same 32-token `clank-theme/1` contract. Tokens cover canvas and\nsurface colors, text hierarchy, borders, accent and danger states, focus, overlay, four radius\nlevels, full rounding, three shadows, sans and mono fonts, control height, density, border width,\nand motion timing.\n\n## Apply a preset\n\nGenerate a static stylesheet during your build, then select a theme through a data attribute:\n\n```ts\nimport {\n  CLANK_THEME_PRESETS,\n  createClankThemeStylesheet,\n} from \"@clank.run/framework/ui/theme\";\n\nconst css = createClankThemeStylesheet(CLANK_THEME_PRESETS);\n// Write `css` to an application-owned stylesheet during the build.\n```\n\n```html\n<html data-clank-theme=\"midnight\">\n```\n\nFor a browser-controlled picker, `applyClankTheme(element, theme)` applies the exact CSS custom\nproperties and color scheme to an element and returns a cleanup function. It never injects remote\nCSS, runs code from a theme, or requires a styling runtime.\n\n```ts\nimport {\n  applyClankTheme,\n  getClankTheme,\n} from \"@clank.run/framework/ui/theme\";\n\nconst midnight = getClankTheme(\"midnight\");\nif (!midnight) throw new Error(\"The built-in Midnight theme is missing.\");\nconst restore = applyClankTheme(document.documentElement, midnight);\n\n// Later, restore the element's previous values.\nrestore();\n```\n\nThe component library remains headless. Presets only provide variables; your CSS or Tailwind\nclasses decide which variables each visual part consumes.\n\n## Define a custom theme\n\nStart with all required tokens and validate the object with `defineClankTheme()`. The function\nrejects missing tokens, unknown tokens, unsafe CSS values, invalid identifiers, and unbounded\nmetadata, then deeply freezes the result.\n\n```ts\nimport {\n  CLANK_THEME_PRESETS,\n  defineClankTheme,\n} from \"@clank.run/framework/ui/theme\";\n\nconst base = CLANK_THEME_PRESETS[0];\n\nexport const ocean = defineClankTheme({\n  id: \"ocean\",\n  name: \"Ocean\",\n  description: \"A calm blue product theme.\",\n  scheme: \"dark\",\n  tags: [\"dark\", \"blue\"],\n  tokens: {\n    ...base.tokens,\n    canvas: \"#06111c\",\n    surface: \"#0b2033\",\n    accent: \"#62d9ff\",\n    accentHover: \"#8ce5ff\",\n    accentContrast: \"#03141c\",\n    focus: \"#8ce5ff\",\n  },\n});\n```\n\nKeeping the complete token record explicit is deliberate: humans and agents can review the whole\ntheme, generated output cannot silently inherit a changing global default, and CSS generation is\ndeterministic.\n\n## Use the Design Studio MCP server\n\nThe workshop exposes a public, read-only Streamable HTTP MCP endpoint:\n\n```json\n{\n  \"mcpServers\": {\n    \"clank-design\": {\n      \"type\": \"http\",\n      \"url\": \"https://design.clank.run/__clank/mcp\"\n    }\n  }\n}\n```\n\nIt does not require a Clank account because it only serves public framework metadata. Available\ntools are:\n\n- `design.components` — list all component families, optionally by module.\n- `design.component` — read one factory, package subpath, parts, and specimen URL.\n- `design.themes` — list the ten preset themes.\n- `design.theme` — read one complete typed token map.\n\nApplication MCP servers remain separate and authenticated. The Design Studio describes framework\nUI contracts; a deployed application's own MCP endpoint describes that application's queries and\nmutations.\n\n## Build and verify locally\n\nFramework contributors can build the studio without installing anything:\n\n```bash\nnpm run build:design\nnode design-site/dist/server.js\n```\n\nThen open `http://127.0.0.1:4400` for local development only. Production documentation and agent\nconfiguration should always use `https://design.clank.run`.\n\nThe root `npm test` and `npm run check` commands build the studio, verify all 37 SSR routes, inspect\nits security headers and immutable assets, exercise both JSON catalogs, and connect to its MCP\nserver. A successful main CI revision can deploy the fixed Design Studio project without changing\nthe public domain.\n"}