@wcomp/elementum 0.0.0-stage → 0.1.0

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.
Files changed (101) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +266 -2
  3. package/custom-elements.json +3613 -0
  4. package/mcp/server.js +408 -0
  5. package/package.json +72 -4
  6. package/skills/elementum-break-ui/CATALOG.md +11 -0
  7. package/skills/elementum-break-ui/SKILL.md +16 -0
  8. package/skills/elementum-mobile/SKILL.md +18 -0
  9. package/skills/elementum-motion/SKILL.md +18 -0
  10. package/skills/elementum-motion/STANDARDS.md +15 -0
  11. package/skills/elementum-penpot/SKILL.md +45 -0
  12. package/skills/elementum-ui/CATALOG.md +14 -0
  13. package/skills/elementum-ui/SKILL.md +21 -0
  14. package/src/ag-ui.js +474 -0
  15. package/src/components/el-accordion.js +201 -0
  16. package/src/components/el-alert-dialog.js +186 -0
  17. package/src/components/el-alert.js +254 -0
  18. package/src/components/el-aspect-ratio.js +73 -0
  19. package/src/components/el-autocomplete.js +775 -0
  20. package/src/components/el-avatar.js +271 -0
  21. package/src/components/el-badge.js +131 -0
  22. package/src/components/el-border-beam.js +135 -0
  23. package/src/components/el-breadcrumb.js +203 -0
  24. package/src/components/el-button.js +220 -0
  25. package/src/components/el-calendar.js +413 -0
  26. package/src/components/el-callout.js +158 -0
  27. package/src/components/el-card.js +298 -0
  28. package/src/components/el-carousel.js +308 -0
  29. package/src/components/el-chart.js +632 -0
  30. package/src/components/el-checkbox-card.js +221 -0
  31. package/src/components/el-checkbox.js +208 -0
  32. package/src/components/el-chip.js +276 -0
  33. package/src/components/el-code-block.js +228 -0
  34. package/src/components/el-collapsible.js +124 -0
  35. package/src/components/el-command.js +556 -0
  36. package/src/components/el-context-menu.js +328 -0
  37. package/src/components/el-data-list.js +210 -0
  38. package/src/components/el-datepicker.js +192 -0
  39. package/src/components/el-dialog.js +272 -0
  40. package/src/components/el-diff-viewer.js +441 -0
  41. package/src/components/el-drawer.js +782 -0
  42. package/src/components/el-dropdown.js +182 -0
  43. package/src/components/el-dropzone.js +242 -0
  44. package/src/components/el-empty-state.js +130 -0
  45. package/src/components/el-field.js +394 -0
  46. package/src/components/el-form.js +185 -0
  47. package/src/components/el-input.js +212 -0
  48. package/src/components/el-inset.js +90 -0
  49. package/src/components/el-insight-card.js +263 -0
  50. package/src/components/el-kbd.js +151 -0
  51. package/src/components/el-menubar.js +254 -0
  52. package/src/components/el-meter.js +182 -0
  53. package/src/components/el-navbar.js +294 -0
  54. package/src/components/el-navigation-menu.js +327 -0
  55. package/src/components/el-number-field.js +510 -0
  56. package/src/components/el-number-flow.js +153 -0
  57. package/src/components/el-otp-input.js +266 -0
  58. package/src/components/el-pagination.js +229 -0
  59. package/src/components/el-popover.js +288 -0
  60. package/src/components/el-preview-card.js +202 -0
  61. package/src/components/el-progress.js +179 -0
  62. package/src/components/el-prompt-input.js +383 -0
  63. package/src/components/el-radio-card.js +360 -0
  64. package/src/components/el-radio.js +257 -0
  65. package/src/components/el-rating.js +165 -0
  66. package/src/components/el-reasoning-card.js +293 -0
  67. package/src/components/el-resizable.js +324 -0
  68. package/src/components/el-router.js +305 -0
  69. package/src/components/el-scroll-area.js +150 -0
  70. package/src/components/el-segmented-control.js +282 -0
  71. package/src/components/el-select.js +219 -0
  72. package/src/components/el-separator.js +85 -0
  73. package/src/components/el-sidebar.js +386 -0
  74. package/src/components/el-skeleton.js +156 -0
  75. package/src/components/el-slider.js +351 -0
  76. package/src/components/el-sources.js +288 -0
  77. package/src/components/el-spinner.js +159 -0
  78. package/src/components/el-streaming-text.js +199 -0
  79. package/src/components/el-switch.js +221 -0
  80. package/src/components/el-table.js +397 -0
  81. package/src/components/el-tabs.js +235 -0
  82. package/src/components/el-task-list.js +230 -0
  83. package/src/components/el-textarea.js +175 -0
  84. package/src/components/el-theme-switch.js +120 -0
  85. package/src/components/el-timeline.js +254 -0
  86. package/src/components/el-toast.js +778 -0
  87. package/src/components/el-toggle.js +311 -0
  88. package/src/components/el-tool-call.js +386 -0
  89. package/src/components/el-toolbar.js +183 -0
  90. package/src/components/el-tooltip.js +172 -0
  91. package/src/components/el-tree-view.js +261 -0
  92. package/src/components/el-visually-hidden.js +32 -0
  93. package/src/elementum.js +485 -0
  94. package/src/index.d.ts +1007 -0
  95. package/src/index.js +99 -0
  96. package/src/signal.js +194 -0
  97. package/src/ssr.js +136 -0
  98. package/src/template.js +321 -0
  99. package/src/tokens.css +416 -0
  100. package/tokens/figma-tokens.json +69 -0
  101. package/tokens/penpot-tokens.json +98 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 wcomp / Elementum Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,267 @@
1
- # Temporary Holding Version
1
+ # @wcomp/elementum
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![CI](https://github.com/pinguxx/Elementum/actions/workflows/ci.yml/badge.svg)](https://github.com/pinguxx/Elementum/actions/workflows/ci.yml)
4
+ ![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)
5
+ ![Zero Dependencies](https://img.shields.io/badge/runtime%20deps-0-success)
6
+ ![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
7
+
8
+ > **Elementum** (*Latin*: /e.leˈmen.tum/) — Direct Latin for *element*, *first principle*, or *foundational matter*.
9
+ >
10
+ > Just as classical philosophy identified *elementa* as the indivisible building blocks of the physical world, **Elementum** returns web UI to its purest primitives: standard Custom Elements, fine-grained micro-signals, and Shadow DOM encapsulation. No virtual DOM diffing, no hydration mismatches, no vendor lock-in, and zero build tool prerequisites.
11
+
12
+ ---
13
+
14
+ ## ⚡ Quick Start
15
+
16
+ Elementum runs directly in any modern browser without Webpack, Vite, or Babel.
17
+
18
+ ```html
19
+ <!DOCTYPE html>
20
+ <html lang="en">
21
+ <head>
22
+ <!-- 1. Include Design Tokens -->
23
+ <link rel="stylesheet" href="https://unpkg.com/@wcomp/elementum/tokens.css" />
24
+
25
+ <!-- 2. Import Component Library -->
26
+ <script type="module" src="https://unpkg.com/@wcomp/elementum"></script>
27
+ </head>
28
+ <body>
29
+ <!-- Native Form with Form-Associated Custom Elements -->
30
+ <form id="my-form">
31
+ <el-input name="username" placeholder="Enter username...">
32
+ <span slot="prefix">👤</span>
33
+ </el-input>
34
+
35
+ <el-select name="role" value="member">
36
+ <option value="member">Team Member</option>
37
+ <option value="admin">Administrator</option>
38
+ </el-select>
39
+
40
+ <el-button type="submit" variant="primary">Save Changes</el-button>
41
+ </form>
42
+ </body>
43
+ </html>
44
+ ```
45
+
46
+ ---
47
+
48
+ ## 💡 Core Principles
49
+
50
+ `Elementum` is inspired by minimalist libraries like `uce`, modernizing the developer experience with standard browser primitives:
51
+ - **Shadow DOM by default** with automatic Constructable Stylesheet adoption (`new CSSStyleSheet()`).
52
+ - **Fine-grained micro-signals** (`signal`, `computed`, `effect`): state updates mutate **only the exact bound DOM text or attribute node**—the component never re-renders, preserving child component state and input focus.
53
+ - **Form-Associated Custom Elements (FACE)**: `static formAssociated = true` enables native `<form>` submission, reset, and validation via `ElementInternals`.
54
+ - **Zero build requirement**: Plain ES modules (`<script type="module">`), no Babel, decorators, or compile step needed. Runs in SSR / Node.js cleanly.
55
+ - **Light & Dark Mode**: Built-in CSS custom property theme tokens with automatic `prefers-color-scheme` and `<el-theme-switch>`.
56
+ - **Leak-free lifecycle**: Automatically tracks and tears down event listeners and signal subscriptions via `this.signal` (`AbortSignal`).
57
+ - **WCAG 2.2 AA Compliant**: Built-in 24x24px minimum target sizes, high-contrast `:focus-visible` rings, dialog focus preservation, and HTML5 Constraint Validation API (`ElementInternals.setValidity`).
58
+ - **Figma 1:1 Parity**: Direct mapping to Figma Component Variants and Figma Variables.
59
+ - **AI Agent & MCP Ready**: Generates standard W3C `custom-elements.json` and includes a built-in MCP server for coding agents.
60
+ - **CI/CD & Automation**: GitHub Actions multi-OS / multi-Node matrix test runner and Dependabot automated dependency updates.
61
+
62
+ ---
63
+
64
+ ## Component Catalog
65
+
66
+ | Component | Tag Name | Description |
67
+ | :--- | :--- | :--- |
68
+ | **Button** | `<el-button>` | 1:1 Figma variant parity (`primary`, `secondary`, `danger`, `ghost`, sizes `sm`/`md`/`lg`). |
69
+ | **Badge** | `<el-badge>` | Status indicator pill (`default`, `success`, `danger`). |
70
+ | **Input** | `<el-input>` | Form-associated input with `prefix` and `suffix` icon slots. |
71
+ | **Dropdown** | `<el-dropdown>` | Popover container with light-dismiss (closes on outside click or <kbd>Esc</kbd>). |
72
+ | **Calendar** | `<el-calendar>` | Standalone 42-day accessible month grid with traversal. |
73
+ | **Datepicker** | `<el-datepicker>` | Form-associated composite datepicker combining input, dropdown, calendar, and quick actions. |
74
+ | **Dialog / Modal** | `<el-dialog>` | Native `<dialog>` modal with backdrop blur, overscroll containment, and light-dismiss. |
75
+ | **Tabs** | `<el-tabs>`, `<el-tab>` | W3C accessible tablist with keyboard arrow navigation. |
76
+ | **Select** | `<el-select>` | Form-associated custom dropdown selection. |
77
+ | **Switch** | `<el-switch>` | Form-associated toggle switch with keyboard navigation (<kbd>Space</kbd>/<kbd>Enter</kbd>). |
78
+ | **Tooltip** | `<el-tooltip>` | Lightweight tooltip bubble with top/bottom/left/right placement. |
79
+ | **Accordion** | `<el-accordion>`, `<el-accordion-item>` | W3C accessible disclosure accordion supporting single or multi-expand. |
80
+ | **Table** | `<el-table>` | Signal-driven data grid with column sorting and multi-row selection. |
81
+ | **Theme Switch** | `<el-theme-switch>` | Toggles between Light ☀️ and Dark 🌙 mode with `localStorage` persistence. |
82
+ | **Toast** | `<el-toaster>` | Viewport overlay for programmatic notifications (`toast.success()`, `toast.error()`). |
83
+ | **Progress** | `<el-progress>` | Determinate & indeterminate animated progress bar (`role="progressbar"`). |
84
+ | **Spinner** | `<el-spinner>` | Accessible SVG loading spinner (`role="status"`). |
85
+ | **Avatar** | `<el-avatar>`, `<el-avatar-group>` | User avatar with image fallback, automatic initials, and status dot. |
86
+ | **Drawer** | `<el-drawer>` | Slide-over drawer overlay (`left`, `right`, `top`, `bottom`) with focus trap. |
87
+ | **Segmented** | `<el-segmented-control>` | Form-associated pill switcher with keyboard arrow navigation. |
88
+ | **Pagination** | `<el-pagination>` | Accessible numeric page navigation with ellipsis windowing and `pagechange` events. |
89
+ | **Chip / Pill** | `<el-chip>` | Interactive tag with `selectable` and `removable` dismiss modes (`role="button"`). |
90
+ | **Autocomplete** | `<el-autocomplete>` | Form-associated combobox supporting single or multiselect (`multiple`) with inline chips, remote URL debouncing, and ARIA 1.2 / WCAG 2.2 accessibility. |
91
+ | **Number Flow** | `<el-number-flow>` | Smooth vertical rolling odometer number reels (*NumberFlow* style) with physical easing and reduced-motion fallback. |
92
+ | **OTP Input** | `<el-otp-input>` | Form-associated segmented PIN / verification code input with auto-advance, backspace retreat, and paste splitting. |
93
+ | **Command Palette** | `<el-command>` | Accessible keyboard-first command menu (*cmdk* style) with <kbd>⌘K</kbd> / <kbd>Ctrl+K</kbd> shortcut, fuzzy search, and group headers. |
94
+ | **Prompt Input** | `<el-prompt-input>` | Beautiful UI-style auto-expanding AI prompt composer with action bar slots, model chips, and Enter-to-submit handling. |
95
+ | **Reasoning Card** | `<el-reasoning-card>` | Collapsible AI thought disclosure with active breathing pulse dot, elapsed duration timer, and smooth accordion expansion. |
96
+ | **Border Beam** | `<el-border-beam>` | Hardware-accelerated luminous gradient ray traveling around container perimeters (Magic UI style). |
97
+ | **Streaming Text** | `<el-streaming-text>` | Organic token-by-token streaming typewriter text with customizable cadence, blinking cursor, and completion events. |
98
+
99
+ ---
100
+
101
+ ## Interactive Examples & Showcase
102
+
103
+ - **[examples/ledgerflow.html](examples/ledgerflow.html)**: **LedgerFlow (Penpot → MCP Generated App)**: End-to-end fintech dashboard designed in **[Penpot](https://design.penpot.app/?screen=viewer&file-id=42288968-6e5e-808d-8008-f77162b618ca&page-id=d8ded059-05ee-80c0-8008-f774c97dd053&section=interactions&index=0&share-id=8218fc5e-f68d-4bab-8fd7-283dd92586e8)** and compiled via `npm run penpot:generate` into 15 validated Elementum Web Components (`<el-number-flow>`, `<el-chart>`, `<el-meter>`, `<el-drawer>`, `<el-dialog>`, `<el-toaster>`).
104
+ - **[examples/references.html](file:///c:/dev/Elementum/examples/references.html)**: **Reference Hub (Anti-AI Slop)**: Real-world patterns reconstructed from curated galleries (SaaS Pricing with rolling odometers & border beams, Linear-style command menu, and segmented PIN auth).
105
+ - **[examples/agent-studio.html](file:///c:/dev/Elementum/examples/agent-studio.html)**: **AI Agent Studio & Command Center** demonstrating `<el-command>` (⌘K), `<el-prompt-input>`, `<el-reasoning-card>`, `<el-number-flow>` live token odometer, `<el-otp-input>` security key authorization, and `<el-border-beam>`.
106
+ - **[index.html](file:///c:/dev/Elementum/index.html)**: Interactive landing portal directing to the applications. Run `npx serve .` to launch locally.
107
+ - **[examples/app.html](file:///c:/dev/Elementum/examples/app.html)**: Complete **Skyline Travel** booking dashboard demonstrating native form validation, confirmation modal dialogs, toast notifications, tabs, and theme toggling.
108
+ - **[examples/index.html](file:///c:/dev/Elementum/examples/index.html)**: Component showcase with standalone controls and live signal-reactive counter.
109
+
110
+ ---
111
+
112
+ ## Design Engineering & Agent Guides
113
+
114
+ ### Installable Agent Skills (`npx skills add`)
115
+ Install Elementum's modular AI coding skills directly into Antigravity, Claude Code, Cursor, or Gemini CLI:
116
+
117
+ ```bash
118
+ npx skills@latest add pinguxx/Elementum
119
+ ```
120
+
121
+ Included skills under [`skills/`](skills/):
122
+ - **`elementum-ui`**: Composing Elementum's 105 Web Components, signals, FACE forms, and AG-UI streams.
123
+ - **`elementum-motion`**: Shadow DOM motion physics, sub-300ms `ease-out`, origin-aware overlays, and reduced-motion standards.
124
+ - **`elementum-break-ui`**: Adversarial stress-testing checklist (320px mobile, dark mode hover contrast, keyboard-only, extreme content).
125
+ - **`elementum-mobile`**: Mobile-native CSS standards (`touch-action`, `100dvh`, safe areas, `overscroll-behavior`, iOS 16px input zoom prevention).
126
+ - **`elementum-penpot`**: Two-way Penpot MCP design system sync and Penpot-to-Elementum app codegen.
127
+
128
+ - **[docs/penpot-workflow.md](file:///c:/dev/Elementum/docs/penpot-workflow.md)**: Free & open-source design token workflow with Penpot (W3C DTCG JSON) and automated compilation.
129
+ - **[docs/agent-craft-guide.md](file:///c:/dev/Elementum/docs/agent-craft-guide.md)**: Guide and system prompt rules for AI coding agents to banish generic AI look and adhere to high-craft standards.
130
+ - **[docs/theming.md](file:///c:/dev/Elementum/docs/theming.md)**: Complete design tokens, CSS custom properties, and `::part()` customization guide.
131
+
132
+ ---
133
+
134
+ ## Framework Integration
135
+
136
+ `@wcomp/elementum` works natively in vanilla HTML, React 19, Vue 3, Svelte 5, and Next.js. See **[docs/framework-integration.md](file:///c:/dev/Elementum/docs/framework-integration.md)** for complete setup instructions and TypeScript configuration.
137
+
138
+ ---
139
+
140
+ ## Project Structure
141
+
142
+ ```
143
+ Elementum/
144
+ ├── .github/
145
+ │ ├── dependabot.yml # Automated weekly dependencies & actions updates
146
+ │ └── workflows/
147
+ │ └── ci.yml # Multi-node, multi-OS CI test workflow
148
+ ├── docs/
149
+ │ └── framework-integration.md # React 19, Vue 3, Svelte 5, and Next.js guide
150
+ ├── src/
151
+ │ ├── signal.js # Micro-signals (~80 lines: signal, computed, effect)
152
+ │ ├── template.js # Tagged template engine (html, css, surgical DOM parts)
153
+ │ ├── elementum.js # Base class with Shadow DOM, styles, and formAssociated
154
+ │ ├── tokens.css # Light & Dark CSS custom properties from Figma
155
+ │ ├── index.js # Public library exports
156
+ │ ├── index.d.ts # Complete TypeScript ambient definitions
157
+ │ └── components/
158
+ │ ├── el-button.js # Reference button matching Figma variants
159
+ │ ├── el-badge.js # Reference badge component
160
+ │ ├── el-input.js # Form-associated input
161
+ │ ├── el-dropdown.js # Light-dismiss dropdown overlay
162
+ │ ├── el-calendar.js # Standalone calendar grid
163
+ │ ├── el-datepicker.js # Composite datepicker
164
+ │ ├── el-dialog.js # Native modal dialog with backdrop containment
165
+ │ ├── el-tabs.js # Accessible W3C tabs with keyboard navigation
166
+ │ ├── el-select.js # Form-associated custom select
167
+ │ ├── el-switch.js # Form-associated toggle switch
168
+ │ ├── el-tooltip.js # Accessible anchored tooltip
169
+ │ ├── el-accordion.js # Accessible disclosure accordion
170
+ │ ├── el-table.js # Reactive data table with sorting and selection
171
+ │ ├── el-toast.js # Programmatic toast notification system
172
+ │ ├── el-theme-switch.js # Light / Dark mode toggle
173
+ │ ├── el-progress.js # Determinate & indeterminate progress bar
174
+ │ ├── el-spinner.js # Animated accessible SVG spinner
175
+ │ ├── el-avatar.js # User avatar & avatar group with fallback
176
+ │ ├── el-drawer.js # Accessible slide-over drawer overlay
177
+ │ ├── el-segmented-control.js # Form-associated pill switcher
178
+ │ ├── el-pagination.js # Accessible numeric pagination controls
179
+ │ ├── el-chip.js # Interactive filter chips & pills
180
+ │ └── el-autocomplete.js # Form-associated combobox & remote search
181
+ ├── tools/
182
+ │ ├── sync-tokens.js # CLI to compile penpot/figma DTCG tokens into tokens.css
183
+ │ ├── sync-penpot-mcp.js # CLI to generate tokens, colors & 105 components in Penpot via MCP
184
+ │ └── create-component.js # CLI to scaffold new components (npm run create)
185
+ ├── custom-elements.json # W3C Custom Elements Manifest (for agents & Storybook)
186
+ ├── AGENT_GUIDE.md # Instructions for AI coding agents & developers
187
+ ├── docs/
188
+ │ ├── theming.md # Design tokens and ::part() customization guide
189
+ │ └── framework-integration.md # React, Vue, Svelte, Angular integration
190
+ ├── examples/
191
+ │ ├── app.html # Full travel booking mini-app
192
+ │ └── index.html # Component showcase
193
+ ├── index.html # Live documentation and demo portal
194
+ ├── mcp/
195
+ │ └── server.js # Model Context Protocol server for AI coding agents
196
+ └── test/ # Node.js automated test runner suite
197
+ ```
198
+
199
+ ---
200
+
201
+ ## 🎨 Theming & Accessibility (WCAG 2.2)
202
+
203
+ - **Theming Guide**: See [docs/theming.md](docs/theming.md) for the full catalog of design tokens and exposed CSS ::part() selectors.
204
+ - **Agent Guide**: See [AGENT_GUIDE.md](AGENT_GUIDE.md) for guidelines on building, testing, and reviewing Elementum components.
205
+ - **Framework Integration**: See [docs/framework-integration.md](docs/framework-integration.md) for React, Vue, Svelte, and Angular setup.
206
+
207
+ ---
208
+
209
+ ## 🚀 Declarative Shadow DOM (DSD) SSR
210
+
211
+ Elementum includes built-in server-side rendering support emitting standard `<template shadowrootmode="open">` for zero-CLS first paint in Next.js, Nuxt, Astro, and Node.js:
212
+
213
+ ```javascript
214
+ import { renderComponentToDSD } from '@wcomp/elementum/ssr';
215
+ import { ElButton } from '@wcomp/elementum';
216
+
217
+ // Outputs HTML with Declarative Shadow DOM and encapsulated styles
218
+ const html = renderComponentToDSD('el-button', ElButton, { variant: 'primary' }, 'Submit');
219
+ ```
220
+
221
+ Run the live zero-dependency Node.js SSR server (`?hydrate=0` for pure Zero-JS DSD, `?hydrate=1` for progressive hydration) or view the pre-rendered snapshot [`examples/ssr-demo.html`](examples/ssr-demo.html):
222
+
223
+ ```bash
224
+ npm run ssr
225
+ ```
226
+
227
+ ---
228
+
229
+ ## Penpot & Figma Design System Sync
230
+
231
+ ### Code → Penpot (MCP Server Sync)
232
+ Generate all **54 W3C DTCG tokens** (Core, Light, Dark sets), **28 library colors**, and **105 Master Components** (across 8 categories) directly inside an open **[Penpot](https://design.penpot.app)** file connected via the Penpot MCP Plugin:
233
+
234
+ ```bash
235
+ npm run penpot:mcp -- --url "https://design.penpot.app/mcp/stream?userToken=<YOUR_TOKEN>"
236
+ # Or via environment variable:
237
+ PENPOT_MCP_URL="https://design.penpot.app/mcp/stream?userToken=<YOUR_TOKEN>" npm run penpot:mcp
238
+ ```
239
+
240
+ ### Penpot / Figma → Code (Token Compiler)
241
+ Synchronize exported W3C DTCG tokens from `tokens/penpot-tokens.json` (or `tokens/figma-tokens.json`) into `src/tokens.css`:
242
+
243
+ ```bash
244
+ npm run tokens:sync tokens/penpot-tokens.json
245
+ ```
246
+
247
+ See **[docs/penpot-workflow.md](docs/penpot-workflow.md)** for full setup instructions, CLI flags (`--url`, `--token`, `--dry-run`), and Penpot MCP security notes.
248
+
249
+ ---
250
+
251
+ ## Agent MCP Server
252
+
253
+ Run the built-in MCP server for AI coding agents:
254
+
255
+ ```bash
256
+ node mcp/server.js
257
+ # Or via package bin
258
+ npx elementum-mcp
259
+ ```
260
+
261
+ Exposed tools:
262
+ - `list_components`: Lists all components in Elementum
263
+ - `get_component_doc`: Retrieves attributes, slots, events, and CSS parts
264
+ - `list_tokens`: Queries design tokens by category (color, spacing, radius)
265
+ - `generate_snippet`: Generates valid HTML markup matching Figma variants
266
+ - `scaffold_component`: Scaffolds standard boilerplate code for new components
267
+ - `validate_accessibility`: Audits component markup against WCAG 2.2 rules