@atelier-ui/create-workspace 0.4.0 → 0.4.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +27 -3
- package/package.json +1 -1
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/SKILL.md +194 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/assets/audit-report-template.md +181 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/audit-checklist.md +462 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/audit-verify-queries.md +414 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/build-from-code-contract.md +87 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/build-workflow.md +260 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/code-sync.md +218 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/code-verify.md +152 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/component-design.md +198 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/decision-heuristics.md +262 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/iconography.md +150 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/inventory-generation.md +433 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/inventory-payload.md +490 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/migration-playbook.md +182 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/naming-and-file-structure.md +161 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/plugin-api-gotchas.md +79 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/scaffold-payload.md +279 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/sync-workflow.md +98 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/token-architecture.md +177 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/tool-map.md +398 -0
- package/src/generators/preset/files/claude/skills/uianatomy-mcp/SKILL.md +160 -0
- package/src/generators/preset/files/contracts/README.md +6 -6
- package/src/generators/preset/files/contracts/types.ts.template +9 -10
- package/src/generators/preset/files/tools/{scripts → design-contracts/bin}/check-contracts.mjs +236 -223
- package/src/generators/preset/files/tools/{scripts → design-contracts/bin}/figma-snapshot-contracts.mjs +107 -92
- package/src/generators/preset/files/tools/design-contracts/src/codespec.mjs +234 -0
- package/src/generators/preset/files/tools/design-contracts/src/config.mjs +63 -0
- package/src/generators/preset/files/tools/{scripts/lib → design-contracts/src}/docgen.mjs +78 -98
- package/src/generators/preset/files/tools/{scripts/lib/ts-eval.js → design-contracts/src/ts-eval.cjs} +3 -4
- package/src/generators/preset/files/tools/scripts/preflight.mjs +1 -1
- package/src/generators/preset/preset.js +79 -15
- package/src/generators/preset/preset.js.map +1 -1
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: uianatomy-mcp
|
|
3
|
+
description: Query the UI Anatomy MCP server for canonical UI component anatomy, axes, slots, transitions, motion, tokens, events, cross-framework mapping, library divergences, and compositional patterns.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# UI Anatomy — MCP skill
|
|
7
|
+
|
|
8
|
+
UI Anatomy publishes a canonical, library-agnostic reference for common UI components (Button, Card, Modal, Tabs, Combobox, Drawer, …). Each component declares its **anatomy** (slots and regions), **axes** (variants, properties, states, transitions), **mismatches** between Figma and code, **common mistakes**, **cross-framework mapping**, **tokens**, **motion**, **responsive** notes, **events**, and **when to use vs. when to avoid**.
|
|
9
|
+
|
|
10
|
+
The MCP server exposes this knowledge as 22 tools.
|
|
11
|
+
|
|
12
|
+
## Endpoint
|
|
13
|
+
|
|
14
|
+
- URL: `https://uianatomy.dev/mcp`
|
|
15
|
+
- Transport: Streamable HTTP (`@modelcontextprotocol/sdk` ≥ 1.29)
|
|
16
|
+
- Auth: none (public read-only)
|
|
17
|
+
- Server card: `https://uianatomy.dev/.well-known/mcp/server-card.json`
|
|
18
|
+
|
|
19
|
+
## Install in another project
|
|
20
|
+
|
|
21
|
+
This skill file is canonical and stable. Drop it into any repo that uses Claude Code and the agent will pick it up automatically.
|
|
22
|
+
|
|
23
|
+
**One-liner:**
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
mkdir -p .claude/skills/uianatomy-mcp \
|
|
27
|
+
&& curl -fsSL -o .claude/skills/uianatomy-mcp/SKILL.md \
|
|
28
|
+
https://uianatomy.dev/.well-known/agent-skills/uianatomy-mcp/SKILL.md
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Then wire the MCP server in the same project's MCP configuration (path varies by client, see below):
|
|
32
|
+
|
|
33
|
+
**Claude Code / Claude Desktop** (`.mcp.json` at project root, or `~/.config/claude/claude_desktop_config.json`):
|
|
34
|
+
|
|
35
|
+
```json
|
|
36
|
+
{
|
|
37
|
+
"mcpServers": {
|
|
38
|
+
"uianatomy": {
|
|
39
|
+
"type": "http",
|
|
40
|
+
"url": "https://uianatomy.dev/mcp"
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
**Older clients without native streamable-HTTP** (Cursor, Windsurf, older Claude Desktop) — proxy via `mcp-remote`:
|
|
47
|
+
|
|
48
|
+
```json
|
|
49
|
+
{
|
|
50
|
+
"mcpServers": {
|
|
51
|
+
"uianatomy": {
|
|
52
|
+
"command": "npx",
|
|
53
|
+
"args": ["-y", "mcp-remote", "https://uianatomy.dev/mcp"]
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
**Direct SDK** (TypeScript / Node ≥ 20):
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
|
|
63
|
+
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
|
|
64
|
+
|
|
65
|
+
const transport = new StreamableHTTPClientTransport(new URL('https://uianatomy.dev/mcp'));
|
|
66
|
+
const client = new Client({ name: 'your-app', version: '1.0.0' });
|
|
67
|
+
await client.connect(transport);
|
|
68
|
+
|
|
69
|
+
const result = await client.callTool({
|
|
70
|
+
name: 'get_anatomy',
|
|
71
|
+
arguments: { id: 'modal' },
|
|
72
|
+
});
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
**Discovery (no install needed)** — every page on `uianatomy.dev` advertises the MCP endpoint via RFC 9727 `Link: rel="api-catalog"`. The agent-skills RFC v0.2.0 index lists this skill at `https://uianatomy.dev/.well-known/agent-skills/index.json`; clients that auto-discover skills will find it.
|
|
76
|
+
|
|
77
|
+
## Tools
|
|
78
|
+
|
|
79
|
+
| Tool | Args | Returns |
|
|
80
|
+
| ---------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
81
|
+
| `list_components` | — | All canonical components (id, name, description). |
|
|
82
|
+
| `search_components` | `query: string` | Substring match across id/name/description/slots/variants. |
|
|
83
|
+
| `get_component` | `id: string` | Full canonical schema for one component. |
|
|
84
|
+
| `get_component_view` | `id: string`, `view: "designer" \| "dev" \| "bridge"` | Role-specific projection of the component. `designer` keeps Figma-side hints + tokens + motion + responsive + property-map + i18n. `dev` keeps code-side hints + framework-map + events + form-integration + a11y-acceptance + performance. `bridge` keeps mismatches + common-mistakes + everything cross-cutting. |
|
|
85
|
+
| `get_anatomy` | `id: string` | Slot/region definitions only. |
|
|
86
|
+
| `get_axes` | `id: string` | Variants, properties, and states only. |
|
|
87
|
+
| `get_mismatches` | `id: string` | Documented Figma ↔ code misalignments. |
|
|
88
|
+
| `get_common_mistakes` | `id: string` | Documented implementation errors and the fixes. |
|
|
89
|
+
| `get_framework_map` | `id: string` | Cross-framework expression mapping (web components / React / Angular signals / Vue). |
|
|
90
|
+
| `get_tokens` | `id: string` | Per-slot token bindings (`spacing`, `radius`, `color`, `elevation`, `typography`). Returns `null` when the component declares none. |
|
|
91
|
+
| `get_motion` | `id: string` | Motion block (durations, easing, reduced-motion fallback). `null` if absent. |
|
|
92
|
+
| `get_responsive` | `id: string` | Responsive breakpoints. `null` if absent. |
|
|
93
|
+
| `get_transitions` | `id: string` | State-machine transitions (`from` / `to` / `trigger`). `null` if absent. |
|
|
94
|
+
| `get_events` | `id: string` | Events array (name, payload, per-framework notes). `null` if absent. |
|
|
95
|
+
| `get_when_to_use` | `id: string` | `use` / `avoid` prose plus related-component differentiators. |
|
|
96
|
+
| `get_changelog` | `id: string` | Versioning metadata: `since` (semver) plus `changelog` array of `{ version, date, summary }`. `null` when neither is declared. |
|
|
97
|
+
| `list_patterns` | — | Every canonical pattern (compositions of canonical components) with `id`, `name`, `description`, the unique `componentId` set composed, and `lastReviewed`. |
|
|
98
|
+
| `get_pattern` | `id: string` | Full canonical pattern record (composition, whenToUse, decisions, mistakes, frameworkSkeletons, lastReviewed). |
|
|
99
|
+
| `get_patterns_for_component` | `componentId: string` | Every pattern that composes the given canonical component, sorted by pattern name, with the role this component plays. Empty array when no pattern uses it. |
|
|
100
|
+
| `list_implementations` | — | Every Phase-2 library audit (one row per library/component pair) — `libraryId`, `componentId`, `componentName`, `divergenceCount`, `lastReviewed`. Sorted by `libraryId` then `componentId`. |
|
|
101
|
+
| `get_implementations` | `componentId: string` | Every library audit for one canonical component as an array of `Implementation` records (`componentId`, `libraryId`, `componentName`, `exampleCode`, `divergence` list, `rationale`, `lastReviewed`). Empty array when no library has audited the component yet. |
|
|
102
|
+
| `validate_implementation` | `componentId: string`, `code: string`, `framework: "react" \| "vue" \| "angular" \| "webComponents"` | Heuristic structural conformance check. Reports which canonical required slots, variants, properties, and events appear (or are missing) in the supplied code. Framework-aware event-name detection (`on<PascalCase>` for React, `@event` / `v-on:` / `emit('event')` for Vue, `(event)` for Angular, bare names for web components). Substring search only — false negatives possible. NOT a substitute for behavioural assertions (pair with the per-component a11y-fixture endpoint and a real Playwright + axe-core run). |
|
|
103
|
+
|
|
104
|
+
## Typical agent flows
|
|
105
|
+
|
|
106
|
+
**"How is a Modal structured?"**
|
|
107
|
+
|
|
108
|
+
1. `get_anatomy({ id: "modal" })` → list of slots with required/optional, purpose, layout hints.
|
|
109
|
+
2. `get_axes({ id: "modal" })` → variants and states.
|
|
110
|
+
3. `get_transitions({ id: "modal" })` → `closed → opening → open → closing → closed`.
|
|
111
|
+
|
|
112
|
+
**"What can go wrong implementing Tabs?"**
|
|
113
|
+
|
|
114
|
+
1. `get_common_mistakes({ id: "tabs" })` → documented errors with rationale.
|
|
115
|
+
2. `get_mismatches({ id: "tabs" })` → Figma ↔ code traps.
|
|
116
|
+
|
|
117
|
+
**"Find a component for filtered selection"**
|
|
118
|
+
|
|
119
|
+
1. `search_components({ query: "filter" })` → ranked candidates.
|
|
120
|
+
2. `get_when_to_use({ id: "combobox" })` → `use`, `avoid`, comparisons with related components.
|
|
121
|
+
|
|
122
|
+
**"How does Radix' Dialog diverge from canonical Modal?"**
|
|
123
|
+
|
|
124
|
+
1. `get_implementations({ componentId: "modal" })` → array of audit records, one per library.
|
|
125
|
+
2. Inspect the `radix` entry's `divergence` list (`omitted` / `renamed` / `extended` / `reshaped`) and `exampleCode` for a known-good wiring.
|
|
126
|
+
|
|
127
|
+
**"I just generated a Modal in React. Did I miss anything canonical?"**
|
|
128
|
+
|
|
129
|
+
1. `validate_implementation({ componentId: "modal", code: "<your code>", framework: "react" })` → structural report listing missing required slots, variants, properties, and events.
|
|
130
|
+
2. Treat `missing` entries as a checklist, not as defects — substring search has false negatives. Run the matching `/api/components/modal/a11y-fixture.json` against your code in a Playwright + `@axe-core/playwright` test for behavioural conformance.
|
|
131
|
+
|
|
132
|
+
## Library implementations (Phase 2)
|
|
133
|
+
|
|
134
|
+
Beyond the canon, three library audits ship today (Radix Dialog, Headless UI Dialog, Angular CDK Dialog), each documenting its **divergence** from canonical Modal as `omitted` / `renamed` / `extended` / `reshaped` entries.
|
|
135
|
+
|
|
136
|
+
Use `list_implementations` for an inventory and `get_implementations({ componentId })` for the full audit records for one canonical component. The same data also renders in the Implementations section of every `/components/<id>` page.
|
|
137
|
+
|
|
138
|
+
## In-browser tools (WebMCP)
|
|
139
|
+
|
|
140
|
+
When loaded in a browser context, every page on `uianatomy.dev` registers three read-only tools via `navigator.modelContext` per the WebMCP draft, backed by the same JSON APIs:
|
|
141
|
+
|
|
142
|
+
- `list_components` — calls `/api/components.json`.
|
|
143
|
+
- `get_component` — calls `/api/components/{id}.json`.
|
|
144
|
+
- `search_components` — fetches the index and substring-filters in-browser.
|
|
145
|
+
|
|
146
|
+
Available without speaking MCP-over-HTTP, useful for browser-resident agents.
|
|
147
|
+
|
|
148
|
+
## No-MCP fallback
|
|
149
|
+
|
|
150
|
+
If a client cannot speak MCP, the same data is available as static JSON:
|
|
151
|
+
|
|
152
|
+
- `GET https://uianatomy.dev/api/components.json` — index.
|
|
153
|
+
- `GET https://uianatomy.dev/api/components/{id}.json` — full canonical schema for one component.
|
|
154
|
+
- `GET https://uianatomy.dev/api/components/{id}/a11y-fixture.json` — `keyboardWalk` + `announcements` + `axeRules` for one component, shaped for direct ingestion into Playwright + `@axe-core/playwright` or Jest + `jest-axe`. Includes an `_about` field describing wiring per assertion type.
|
|
155
|
+
|
|
156
|
+
Pages also serve markdown on `Accept: text/markdown` (with `Content-Type: text/markdown; charset=utf-8` and `x-markdown-tokens` headers); useful for agents that prefer prose context over JSON schemas.
|
|
157
|
+
|
|
158
|
+
## Authority
|
|
159
|
+
|
|
160
|
+
Both the website and the MCP server are generated from the same canonical YAML in `content/components/` against a single Zod schema. No separate data store, no drift. Source of truth: <https://github.com/dominikpieper/uianatomy>.
|
|
@@ -19,16 +19,16 @@ change and points at the task item tracking it; being drawn makes an entry owed
|
|
|
19
19
|
not decide the answer, and deleting the axis from the master is often the honest one
|
|
20
20
|
(interaction states are CSS pseudo-classes here by convention, ADR-0114).
|
|
21
21
|
|
|
22
|
-
The
|
|
23
|
-
|
|
24
|
-
object literal (no imports of values, no computed members).
|
|
22
|
+
The check (`check-contracts`, from `@conciso/design-contracts`) reads each
|
|
23
|
+
`<name>.contract.ts` statically (it evaluates the literal and never runs the file), so a
|
|
24
|
+
contract must stay a plain object literal (no imports of values, no computed members).
|
|
25
25
|
|
|
26
26
|
Every component story meta whose component has a contract must import it and set
|
|
27
27
|
`contract` in its `parameters` (`docs-block.ts`'s `ContractBlock` reads
|
|
28
28
|
`parameters.contract` to render the "Contract" section on the docs page); a story file
|
|
29
|
-
that has a contract but doesn't wire it in is `[CONTRACT-IMPORT]` —
|
|
30
|
-
`
|
|
31
|
-
scaffolded workspace until it
|
|
29
|
+
that has a contract but doesn't wire it in is `[CONTRACT-IMPORT]` — its severity is the
|
|
30
|
+
`contractImportSeverity` setting in `contracts.config.json` (an error in the Atelier
|
|
31
|
+
monorepo, which ships the block; a warning in a scaffolded workspace until it does).
|
|
32
32
|
|
|
33
33
|
To add one: create `<kebab-selector-without-atl-prefix>.contract.ts` in the contracts
|
|
34
34
|
directory (`AtlButton` → `button.contract.ts`), `import type { ComponentContract } from
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The micro-contract
|
|
2
|
+
* The micro-contract: the ONLY hand-authored spec artefact per
|
|
3
3
|
* component. It records what no derived artefact can know — which Figma master this
|
|
4
4
|
* component is, and where Figma and code differ on purpose. Everything else about the
|
|
5
5
|
* component is derived: props, types, defaults and descriptions from the docgen manifest;
|
|
@@ -12,23 +12,22 @@
|
|
|
12
12
|
* metadata file has failed.
|
|
13
13
|
*
|
|
14
14
|
* Contracts are plain object literals — no imports of values, no computed members — so
|
|
15
|
-
*
|
|
16
|
-
* registry.
|
|
15
|
+
* the check can read them statically (it evaluates the literal, it never runs the file).
|
|
17
16
|
*/
|
|
18
17
|
export interface ComponentContract {
|
|
19
|
-
/** Spec selector, e.g. `'
|
|
18
|
+
/** Spec selector, e.g. `'Button'`. Must equal the master's `selector` in the Figma snapshot. */
|
|
20
19
|
component: string;
|
|
21
|
-
/** The master's `COMPONENT_SET` (or lone `COMPONENT`) node id in the
|
|
20
|
+
/** The master's `COMPONENT_SET` (or lone `COMPONENT`) node id in the Figma file, e.g. `'129:20'`. */
|
|
22
21
|
figmaNodeId: string;
|
|
23
22
|
/**
|
|
24
23
|
* Figma properties — variant axes, Booleans, Texts, instance swaps — that have no code
|
|
25
24
|
* prop on purpose, each with the reason. The `state` axis is NOT listed: interaction
|
|
26
|
-
* states are CSS pseudo-classes by
|
|
25
|
+
* states are CSS pseudo-classes by convention and the check knows it.
|
|
27
26
|
*/
|
|
28
27
|
figmaOnly?: ReadonlyArray<{ name: string; reason: string }>;
|
|
29
28
|
/**
|
|
30
29
|
* Code props or events that have no Figma property on purpose, each with the reason
|
|
31
|
-
* (e.g. `open` — "false renders nothing"
|
|
30
|
+
* (e.g. `open` — "false renders nothing"). Domain: only string-literal enum
|
|
32
31
|
* props — the code's own axes — ever need an entry here, for the same reason
|
|
33
32
|
* `[ENUM-UNDRAWN]` only ever reports enum props. Booleans, strings, numbers, callbacks
|
|
34
33
|
* and events with no Figma counterpart are normal (behaviour and content) and never
|
|
@@ -39,10 +38,10 @@ export interface ComponentContract {
|
|
|
39
38
|
* A Figma axis that maps to a code prop under another name or value set, e.g. the
|
|
40
39
|
* `selection` axis (`checked` | `unchecked`) that is `checked: boolean` in code.
|
|
41
40
|
* Verbatim-equal axes need no entry. `codeProp` may be dotted (`Child.prop`, e.g.
|
|
42
|
-
* `
|
|
41
|
+
* `Step.completed`) when the prop lives on a CHILD component's own manifest rather
|
|
43
42
|
* than the story's primary component — the check resolves it there. Several entries
|
|
44
|
-
* may target the same `figmaAxis` (e.g.
|
|
45
|
-
* different `
|
|
43
|
+
* may target the same `figmaAxis` (e.g. Stepper's `state` axis maps to three
|
|
44
|
+
* different `Step` flags, one entry each).
|
|
46
45
|
*/
|
|
47
46
|
axisMap?: ReadonlyArray<{
|
|
48
47
|
figmaAxis: string;
|