@wcomp/elementum 0.0.0-stage → 0.2.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 (102) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +282 -2
  3. package/custom-elements.json +3613 -0
  4. package/mcp/server.js +593 -0
  5. package/package.json +77 -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/behaviors/index.js +760 -0
  16. package/src/components/el-accordion.js +201 -0
  17. package/src/components/el-alert-dialog.js +186 -0
  18. package/src/components/el-alert.js +254 -0
  19. package/src/components/el-aspect-ratio.js +73 -0
  20. package/src/components/el-autocomplete.js +775 -0
  21. package/src/components/el-avatar.js +271 -0
  22. package/src/components/el-badge.js +131 -0
  23. package/src/components/el-border-beam.js +135 -0
  24. package/src/components/el-breadcrumb.js +203 -0
  25. package/src/components/el-button.js +231 -0
  26. package/src/components/el-calendar.js +436 -0
  27. package/src/components/el-callout.js +158 -0
  28. package/src/components/el-card.js +298 -0
  29. package/src/components/el-carousel.js +308 -0
  30. package/src/components/el-chart.js +632 -0
  31. package/src/components/el-checkbox-card.js +221 -0
  32. package/src/components/el-checkbox.js +208 -0
  33. package/src/components/el-chip.js +276 -0
  34. package/src/components/el-code-block.js +230 -0
  35. package/src/components/el-collapsible.js +124 -0
  36. package/src/components/el-command.js +556 -0
  37. package/src/components/el-context-menu.js +328 -0
  38. package/src/components/el-data-list.js +210 -0
  39. package/src/components/el-datepicker.js +192 -0
  40. package/src/components/el-dialog.js +272 -0
  41. package/src/components/el-diff-viewer.js +441 -0
  42. package/src/components/el-drawer.js +782 -0
  43. package/src/components/el-dropdown.js +182 -0
  44. package/src/components/el-dropzone.js +242 -0
  45. package/src/components/el-empty-state.js +130 -0
  46. package/src/components/el-field.js +394 -0
  47. package/src/components/el-form.js +185 -0
  48. package/src/components/el-input.js +229 -0
  49. package/src/components/el-inset.js +90 -0
  50. package/src/components/el-insight-card.js +263 -0
  51. package/src/components/el-kbd.js +151 -0
  52. package/src/components/el-menubar.js +254 -0
  53. package/src/components/el-meter.js +183 -0
  54. package/src/components/el-navbar.js +294 -0
  55. package/src/components/el-navigation-menu.js +327 -0
  56. package/src/components/el-number-field.js +510 -0
  57. package/src/components/el-number-flow.js +164 -0
  58. package/src/components/el-otp-input.js +266 -0
  59. package/src/components/el-pagination.js +231 -0
  60. package/src/components/el-popover.js +288 -0
  61. package/src/components/el-preview-card.js +202 -0
  62. package/src/components/el-progress.js +179 -0
  63. package/src/components/el-prompt-input.js +383 -0
  64. package/src/components/el-radio-card.js +360 -0
  65. package/src/components/el-radio.js +257 -0
  66. package/src/components/el-rating.js +165 -0
  67. package/src/components/el-reasoning-card.js +293 -0
  68. package/src/components/el-resizable.js +324 -0
  69. package/src/components/el-router.js +305 -0
  70. package/src/components/el-scroll-area.js +150 -0
  71. package/src/components/el-segmented-control.js +282 -0
  72. package/src/components/el-select.js +220 -0
  73. package/src/components/el-separator.js +85 -0
  74. package/src/components/el-sidebar.js +386 -0
  75. package/src/components/el-skeleton.js +156 -0
  76. package/src/components/el-slider.js +351 -0
  77. package/src/components/el-sources.js +288 -0
  78. package/src/components/el-spinner.js +159 -0
  79. package/src/components/el-streaming-text.js +199 -0
  80. package/src/components/el-switch.js +221 -0
  81. package/src/components/el-table.js +397 -0
  82. package/src/components/el-tabs.js +235 -0
  83. package/src/components/el-task-list.js +230 -0
  84. package/src/components/el-textarea.js +175 -0
  85. package/src/components/el-theme-switch.js +120 -0
  86. package/src/components/el-timeline.js +254 -0
  87. package/src/components/el-toast.js +778 -0
  88. package/src/components/el-toggle.js +311 -0
  89. package/src/components/el-tool-call.js +386 -0
  90. package/src/components/el-toolbar.js +183 -0
  91. package/src/components/el-tooltip.js +172 -0
  92. package/src/components/el-tree-view.js +261 -0
  93. package/src/components/el-visually-hidden.js +32 -0
  94. package/src/elementum.js +504 -0
  95. package/src/index.d.ts +1093 -0
  96. package/src/index.js +112 -0
  97. package/src/signal.js +215 -0
  98. package/src/ssr.js +136 -0
  99. package/src/template.js +321 -0
  100. package/src/tokens.css +416 -0
  101. package/tokens/figma-tokens.json +69 -0
  102. 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,283 @@
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/) — **An AI-native, framework-independent UI engineering platform** built on standard Custom Elements, fine-grained micro-signals, W3C DTCG tokens, Declarative Shadow DOM SSR, and MCP/AG-UI tooling.
9
+ >
10
+ > **Live Showcase:** https://elementum-sage.vercel.app/ · **Catalog (109 elements):** https://elementum-sage.vercel.app/examples/index.html · **AG-UI Demo:** https://elementum-sage.vercel.app/examples/ag-ui.html · **Live DSD SSR:** https://elementum-sage.vercel.app/ssr
11
+
12
+ ---
13
+
14
+ ## 🧪 Verification & Browser Matrix (Beta — `v0.2.0`)
15
+
16
+ Every architectural claim in Elementum is backed by automated verification in CI:
17
+
18
+ | Verification Layer | Tooling | Scope |
19
+ | :--- | :--- | :--- |
20
+ | **Core Signals & Fuzzing** | `node:test` (`test/signal-torture.test.js`) | Cycle detection, stale-dep cleanup, AbortSignal disposal, 100-graph randomized DAG fuzzer |
21
+ | **Unit & Contract Suite** | `node:test` + `happy-dom` (Node 20/22/24, Ubuntu & Windows) | **208+ tests**, **≥ 95% line coverage**, automated Source-vs-Catalog Diff (`npm run catalog:diff`) |
22
+ | **Real Browser E2E** | Playwright (`npm run test:e2e`) — Chromium, Firefox, WebKit | Native `<dialog>` focus restoration, `ElementInternals` `<form>` submit/reset, mobile `375px` overflow, AG-UI SSE |
23
+ | **Declarative Shadow DOM SSR** | Playwright (`/?hydrate=0` Zero-JS & `/?hydrate=1` Hydrated) | Native `<template shadowrootmode="open">` attachment with JS disabled + clean client hydration |
24
+ | **Accessibility** | `@axe-core/playwright` (WCAG 2.2 AA ruleset) + MCP `lint_accessibility` | Automated real-browser `axe-core` checks on Home, AG-UI, and SSR pages |
25
+ | **Security & MCP Hardening** | `test/security.test.js` | XSS escaping in `template.js` & `ssr.js`, URL sanitization, prototype-pollution guards, 128 KB MCP payload cap |
26
+ | **Performance Benchmarks** | `npm run bench` (`tools/benchmark.js`) | 10,000 signal updates in ~7 ms · 1,000 DSD SSR renders in ~15 ms · 1,000 DOM mounts in ~60 ms |
27
+
28
+ ---
29
+
30
+ ## ⚡ Quick Start
31
+
32
+ Elementum runs directly in any modern browser without Webpack, Vite, or Babel.
33
+
34
+ ```html
35
+ <!DOCTYPE html>
36
+ <html lang="en">
37
+ <head>
38
+ <!-- 1. Include Design Tokens -->
39
+ <link rel="stylesheet" href="https://unpkg.com/@wcomp/elementum/tokens.css" />
40
+
41
+ <!-- 2. Import Component Library -->
42
+ <script type="module" src="https://unpkg.com/@wcomp/elementum"></script>
43
+ </head>
44
+ <body>
45
+ <!-- Native Form with Form-Associated Custom Elements -->
46
+ <form id="my-form">
47
+ <el-input name="username" placeholder="Enter username...">
48
+ <span slot="prefix">👤</span>
49
+ </el-input>
50
+
51
+ <el-select name="role" value="member">
52
+ <option value="member">Team Member</option>
53
+ <option value="admin">Administrator</option>
54
+ </el-select>
55
+
56
+ <el-button type="submit" variant="primary">Save Changes</el-button>
57
+ </form>
58
+ </body>
59
+ </html>
60
+ ```
61
+
62
+ ---
63
+
64
+ ## 💡 Core Principles
65
+
66
+ `Elementum` is inspired by minimalist libraries like `uce`, modernizing the developer experience with standard browser primitives:
67
+ - **Shadow DOM by default** with automatic Constructable Stylesheet adoption (`new CSSStyleSheet()`).
68
+ - **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.
69
+ - **Form-Associated Custom Elements (FACE)**: `static formAssociated = true` enables native `<form>` submission, reset, and validation via `ElementInternals`.
70
+ - **Zero build requirement**: Plain ES modules (`<script type="module">`), no Babel, decorators, or compile step needed. Runs in SSR / Node.js cleanly.
71
+ - **Light & Dark Mode**: Built-in CSS custom property theme tokens with automatic `prefers-color-scheme` and `<el-theme-switch>`.
72
+ - **Leak-free lifecycle**: Automatically tracks and tears down event listeners and signal subscriptions via `this.signal` (`AbortSignal`).
73
+ - **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`).
74
+ - **Figma 1:1 Parity**: Direct mapping to Figma Component Variants and Figma Variables.
75
+ - **AI Agent & MCP Ready**: Generates standard W3C `custom-elements.json` and includes a built-in MCP server for coding agents.
76
+ - **CI/CD & Automation**: GitHub Actions multi-OS / multi-Node matrix test runner and Dependabot automated dependency updates.
77
+
78
+ ---
79
+
80
+ ## Component Catalog
81
+
82
+ | Component | Tag Name | Description |
83
+ | :--- | :--- | :--- |
84
+ | **Button** | `<el-button>` | 1:1 Figma variant parity (`primary`, `secondary`, `danger`, `ghost`, sizes `sm`/`md`/`lg`). |
85
+ | **Badge** | `<el-badge>` | Status indicator pill (`default`, `success`, `danger`). |
86
+ | **Input** | `<el-input>` | Form-associated input with `prefix` and `suffix` icon slots. |
87
+ | **Dropdown** | `<el-dropdown>` | Popover container with light-dismiss (closes on outside click or <kbd>Esc</kbd>). |
88
+ | **Calendar** | `<el-calendar>` | Standalone 42-day accessible month grid with traversal. |
89
+ | **Datepicker** | `<el-datepicker>` | Form-associated composite datepicker combining input, dropdown, calendar, and quick actions. |
90
+ | **Dialog / Modal** | `<el-dialog>` | Native `<dialog>` modal with backdrop blur, overscroll containment, and light-dismiss. |
91
+ | **Tabs** | `<el-tabs>`, `<el-tab>` | W3C accessible tablist with keyboard arrow navigation. |
92
+ | **Select** | `<el-select>` | Form-associated custom dropdown selection. |
93
+ | **Switch** | `<el-switch>` | Form-associated toggle switch with keyboard navigation (<kbd>Space</kbd>/<kbd>Enter</kbd>). |
94
+ | **Tooltip** | `<el-tooltip>` | Lightweight tooltip bubble with top/bottom/left/right placement. |
95
+ | **Accordion** | `<el-accordion>`, `<el-accordion-item>` | W3C accessible disclosure accordion supporting single or multi-expand. |
96
+ | **Table** | `<el-table>` | Signal-driven data grid with column sorting and multi-row selection. |
97
+ | **Theme Switch** | `<el-theme-switch>` | Toggles between Light ☀️ and Dark 🌙 mode with `localStorage` persistence. |
98
+ | **Toast** | `<el-toaster>` | Viewport overlay for programmatic notifications (`toast.success()`, `toast.error()`). |
99
+ | **Progress** | `<el-progress>` | Determinate & indeterminate animated progress bar (`role="progressbar"`). |
100
+ | **Spinner** | `<el-spinner>` | Accessible SVG loading spinner (`role="status"`). |
101
+ | **Avatar** | `<el-avatar>`, `<el-avatar-group>` | User avatar with image fallback, automatic initials, and status dot. |
102
+ | **Drawer** | `<el-drawer>` | Slide-over drawer overlay (`left`, `right`, `top`, `bottom`) with focus trap. |
103
+ | **Segmented** | `<el-segmented-control>` | Form-associated pill switcher with keyboard arrow navigation. |
104
+ | **Pagination** | `<el-pagination>` | Accessible numeric page navigation with ellipsis windowing and `pagechange` events. |
105
+ | **Chip / Pill** | `<el-chip>` | Interactive tag with `selectable` and `removable` dismiss modes (`role="button"`). |
106
+ | **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. |
107
+ | **Number Flow** | `<el-number-flow>` | Smooth vertical rolling odometer number reels (*NumberFlow* style) with physical easing and reduced-motion fallback. |
108
+ | **OTP Input** | `<el-otp-input>` | Form-associated segmented PIN / verification code input with auto-advance, backspace retreat, and paste splitting. |
109
+ | **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. |
110
+ | **Prompt Input** | `<el-prompt-input>` | Beautiful UI-style auto-expanding AI prompt composer with action bar slots, model chips, and Enter-to-submit handling. |
111
+ | **Reasoning Card** | `<el-reasoning-card>` | Collapsible AI thought disclosure with active breathing pulse dot, elapsed duration timer, and smooth accordion expansion. |
112
+ | **Border Beam** | `<el-border-beam>` | Hardware-accelerated luminous gradient ray traveling around container perimeters (Magic UI style). |
113
+ | **Streaming Text** | `<el-streaming-text>` | Organic token-by-token streaming typewriter text with customizable cadence, blinking cursor, and completion events. |
114
+
115
+ ---
116
+
117
+ ## Interactive Examples & Showcase
118
+
119
+ - **[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>`).
120
+ - **[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).
121
+ - **[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>`.
122
+ - **[index.html](file:///c:/dev/Elementum/index.html)**: Interactive landing portal directing to the applications. Run `npx serve .` to launch locally.
123
+ - **[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.
124
+ - **[examples/index.html](file:///c:/dev/Elementum/examples/index.html)**: Component showcase with standalone controls and live signal-reactive counter.
125
+
126
+ ---
127
+
128
+ ## Design Engineering & Agent Guides
129
+
130
+ ### Installable Agent Skills (`npx skills add`)
131
+ Install Elementum's modular AI coding skills directly into Antigravity, Claude Code, Cursor, or Gemini CLI:
132
+
133
+ ```bash
134
+ npx skills@latest add pinguxx/Elementum
135
+ ```
136
+
137
+ Included skills under [`skills/`](skills/):
138
+ - **`elementum-ui`**: Composing Elementum's 105 Web Components, signals, FACE forms, and AG-UI streams.
139
+ - **`elementum-motion`**: Shadow DOM motion physics, sub-300ms `ease-out`, origin-aware overlays, and reduced-motion standards.
140
+ - **`elementum-break-ui`**: Adversarial stress-testing checklist (320px mobile, dark mode hover contrast, keyboard-only, extreme content).
141
+ - **`elementum-mobile`**: Mobile-native CSS standards (`touch-action`, `100dvh`, safe areas, `overscroll-behavior`, iOS 16px input zoom prevention).
142
+ - **`elementum-penpot`**: Two-way Penpot MCP design system sync and Penpot-to-Elementum app codegen.
143
+
144
+ - **[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.
145
+ - **[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.
146
+ - **[docs/theming.md](file:///c:/dev/Elementum/docs/theming.md)**: Complete design tokens, CSS custom properties, and `::part()` customization guide.
147
+
148
+ ---
149
+
150
+ ## Framework Integration
151
+
152
+ `@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.
153
+
154
+ ---
155
+
156
+ ## Project Structure
157
+
158
+ ```
159
+ Elementum/
160
+ ├── .github/
161
+ │ ├── dependabot.yml # Automated weekly dependencies & actions updates
162
+ │ └── workflows/
163
+ │ └── ci.yml # Multi-node, multi-OS CI test workflow
164
+ ├── docs/
165
+ │ └── framework-integration.md # React 19, Vue 3, Svelte 5, and Next.js guide
166
+ ├── src/
167
+ │ ├── signal.js # Micro-signals (~80 lines: signal, computed, effect)
168
+ │ ├── template.js # Tagged template engine (html, css, surgical DOM parts)
169
+ │ ├── elementum.js # Base class with Shadow DOM, styles, and formAssociated
170
+ │ ├── tokens.css # Light & Dark CSS custom properties from Figma
171
+ │ ├── index.js # Public library exports
172
+ │ ├── index.d.ts # Complete TypeScript ambient definitions
173
+ │ └── components/
174
+ │ ├── el-button.js # Reference button matching Figma variants
175
+ │ ├── el-badge.js # Reference badge component
176
+ │ ├── el-input.js # Form-associated input
177
+ │ ├── el-dropdown.js # Light-dismiss dropdown overlay
178
+ │ ├── el-calendar.js # Standalone calendar grid
179
+ │ ├── el-datepicker.js # Composite datepicker
180
+ │ ├── el-dialog.js # Native modal dialog with backdrop containment
181
+ │ ├── el-tabs.js # Accessible W3C tabs with keyboard navigation
182
+ │ ├── el-select.js # Form-associated custom select
183
+ │ ├── el-switch.js # Form-associated toggle switch
184
+ │ ├── el-tooltip.js # Accessible anchored tooltip
185
+ │ ├── el-accordion.js # Accessible disclosure accordion
186
+ │ ├── el-table.js # Reactive data table with sorting and selection
187
+ │ ├── el-toast.js # Programmatic toast notification system
188
+ │ ├── el-theme-switch.js # Light / Dark mode toggle
189
+ │ ├── el-progress.js # Determinate & indeterminate progress bar
190
+ │ ├── el-spinner.js # Animated accessible SVG spinner
191
+ │ ├── el-avatar.js # User avatar & avatar group with fallback
192
+ │ ├── el-drawer.js # Accessible slide-over drawer overlay
193
+ │ ├── el-segmented-control.js # Form-associated pill switcher
194
+ │ ├── el-pagination.js # Accessible numeric pagination controls
195
+ │ ├── el-chip.js # Interactive filter chips & pills
196
+ │ └── el-autocomplete.js # Form-associated combobox & remote search
197
+ ├── tools/
198
+ │ ├── sync-tokens.js # CLI to compile penpot/figma DTCG tokens into tokens.css
199
+ │ ├── sync-penpot-mcp.js # CLI to generate tokens, colors & 105 components in Penpot via MCP
200
+ │ └── create-component.js # CLI to scaffold new components (npm run create)
201
+ ├── custom-elements.json # W3C Custom Elements Manifest (for agents & Storybook)
202
+ ├── AGENT_GUIDE.md # Instructions for AI coding agents & developers
203
+ ├── docs/
204
+ │ ├── theming.md # Design tokens and ::part() customization guide
205
+ │ └── framework-integration.md # React, Vue, Svelte, Angular integration
206
+ ├── examples/
207
+ │ ├── app.html # Full travel booking mini-app
208
+ │ └── index.html # Component showcase
209
+ ├── index.html # Live documentation and demo portal
210
+ ├── mcp/
211
+ │ └── server.js # Model Context Protocol server for AI coding agents
212
+ └── test/ # Node.js automated test runner suite
213
+ ```
214
+
215
+ ---
216
+
217
+ ## 🎨 Theming & Accessibility (WCAG 2.2)
218
+
219
+ - **Theming Guide**: See [docs/theming.md](docs/theming.md) for the full catalog of design tokens and exposed CSS ::part() selectors.
220
+ - **Agent Guide**: See [AGENT_GUIDE.md](AGENT_GUIDE.md) for guidelines on building, testing, and reviewing Elementum components.
221
+ - **Framework Integration**: See [docs/framework-integration.md](docs/framework-integration.md) for React, Vue, Svelte, and Angular setup.
222
+
223
+ ---
224
+
225
+ ## 🚀 Declarative Shadow DOM (DSD) SSR
226
+
227
+ 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:
228
+
229
+ ```javascript
230
+ import { renderComponentToDSD } from '@wcomp/elementum/ssr';
231
+ import { ElButton } from '@wcomp/elementum';
232
+
233
+ // Outputs HTML with Declarative Shadow DOM and encapsulated styles
234
+ const html = renderComponentToDSD('el-button', ElButton, { variant: 'primary' }, 'Submit');
235
+ ```
236
+
237
+ 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):
238
+
239
+ ```bash
240
+ npm run ssr
241
+ ```
242
+
243
+ ---
244
+
245
+ ## Penpot & Figma Design System Sync
246
+
247
+ ### Code → Penpot (MCP Server Sync)
248
+ 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:
249
+
250
+ ```bash
251
+ npm run penpot:mcp -- --url "https://design.penpot.app/mcp/stream?userToken=<YOUR_TOKEN>"
252
+ # Or via environment variable:
253
+ PENPOT_MCP_URL="https://design.penpot.app/mcp/stream?userToken=<YOUR_TOKEN>" npm run penpot:mcp
254
+ ```
255
+
256
+ ### Penpot / Figma → Code (Token Compiler)
257
+ Synchronize exported W3C DTCG tokens from `tokens/penpot-tokens.json` (or `tokens/figma-tokens.json`) into `src/tokens.css`:
258
+
259
+ ```bash
260
+ npm run tokens:sync tokens/penpot-tokens.json
261
+ ```
262
+
263
+ See **[docs/penpot-workflow.md](docs/penpot-workflow.md)** for full setup instructions, CLI flags (`--url`, `--token`, `--dry-run`), and Penpot MCP security notes.
264
+
265
+ ---
266
+
267
+ ## Agent MCP Server
268
+
269
+ Run the built-in MCP server for AI coding agents:
270
+
271
+ ```bash
272
+ node mcp/server.js
273
+ # Or via package bin
274
+ npx elementum-mcp
275
+ ```
276
+
277
+ Exposed tools:
278
+ - `list_components`: Lists all components in Elementum
279
+ - `get_component_doc`: Retrieves attributes, slots, events, and CSS parts
280
+ - `list_tokens`: Queries design tokens by category (color, spacing, radius)
281
+ - `generate_snippet`: Generates valid HTML markup matching Figma variants
282
+ - `scaffold_component`: Scaffolds standard boilerplate code for new components
283
+ - `validate_accessibility`: Audits component markup against WCAG 2.2 rules