@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/mcp/server.js ADDED
@@ -0,0 +1,408 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Elementum Design System MCP Server
4
+ * Exposes component schemas, tokens, and markup generation tools to AI coding agents.
5
+ */
6
+
7
+ import fs from 'node:fs';
8
+ import path from 'node:path';
9
+ import { fileURLToPath } from 'node:url';
10
+ import readline from 'node:readline';
11
+
12
+ const __dirname = path.dirname(fileURLToPath(import.meta.url));
13
+ const rootDir = path.resolve(__dirname, '..');
14
+
15
+ // Load Custom Elements Manifest and Figma Tokens
16
+ const manifestPath = path.join(rootDir, 'custom-elements.json');
17
+ const tokensPath = path.join(rootDir, 'tokens', 'figma-tokens.json');
18
+
19
+ const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
20
+ const tokens = JSON.parse(fs.readFileSync(tokensPath, 'utf8'));
21
+
22
+ const TOOLS = [
23
+ {
24
+ name: 'list_components',
25
+ description: 'Lists all available Web Components in the Elementum Design System.',
26
+ inputSchema: {
27
+ type: 'object',
28
+ properties: {},
29
+ },
30
+ },
31
+ {
32
+ name: 'get_component_doc',
33
+ description: 'Retrieves attributes, slots, events, and CSS parts for an Elementum component.',
34
+ inputSchema: {
35
+ type: 'object',
36
+ properties: {
37
+ tag: {
38
+ type: 'string',
39
+ description: 'The custom element tag name, e.g. "el-button" or "el-badge"',
40
+ },
41
+ },
42
+ required: ['tag'],
43
+ },
44
+ },
45
+ {
46
+ name: 'list_tokens',
47
+ description: 'Lists Figma design tokens (colors, spacing, radii) for the design system.',
48
+ inputSchema: {
49
+ type: 'object',
50
+ properties: {
51
+ category: {
52
+ type: 'string',
53
+ enum: ['color', 'spacing', 'radius', 'all'],
54
+ description: 'Token category to filter by.',
55
+ },
56
+ },
57
+ },
58
+ },
59
+ {
60
+ name: 'generate_snippet',
61
+ description: 'Generates valid Elementum Web Component HTML markup matching Figma variants.',
62
+ inputSchema: {
63
+ type: 'object',
64
+ properties: {
65
+ tag: { type: 'string', description: 'Component tag, e.g. "el-button"' },
66
+ variant: { type: 'string', description: 'Visual variant, e.g. "primary", "secondary", "danger"' },
67
+ size: { type: 'string', description: 'Size variant, e.g. "sm", "md", "lg"' },
68
+ label: { type: 'string', description: 'Content text for the default slot' },
69
+ disabled: { type: 'boolean', description: 'Whether the element is disabled' },
70
+ },
71
+ required: ['tag'],
72
+ },
73
+ },
74
+ {
75
+ name: 'scaffold_component',
76
+ description: 'Scaffolds standard boilerplate JavaScript code for a new Elementum Web Component adhering to design system standards.',
77
+ inputSchema: {
78
+ type: 'object',
79
+ properties: {
80
+ tag: { type: 'string', description: 'Component tag, e.g. "el-card"' },
81
+ name: { type: 'string', description: 'Component class name, e.g. "ElCard"' },
82
+ description: { type: 'string', description: 'Component description' },
83
+ formAssociated: { type: 'boolean', description: 'Whether the component associates with forms' },
84
+ attributes: {
85
+ type: 'array',
86
+ items: { type: 'string' },
87
+ description: 'Observed attributes, e.g. ["variant", "disabled"]',
88
+ },
89
+ },
90
+ required: ['tag'],
91
+ },
92
+ },
93
+ {
94
+ name: 'validate_accessibility',
95
+ description: 'Audits Elementum component usage or HTML markup against WCAG 2.2 accessibility standards.',
96
+ inputSchema: {
97
+ type: 'object',
98
+ properties: {
99
+ markup: { type: 'string', description: 'HTML markup snippet to inspect' },
100
+ },
101
+ required: ['markup'],
102
+ },
103
+ },
104
+ ];
105
+
106
+ function handleToolCall(name, args) {
107
+ if (name === 'list_components') {
108
+ const list = manifest.modules.flatMap((m) =>
109
+ m.declarations.map((d) => ({
110
+ tag: d.tagName,
111
+ name: d.name,
112
+ description: d.description,
113
+ }))
114
+ );
115
+ return { components: list };
116
+ }
117
+
118
+ if (name === 'get_component_doc') {
119
+ const match = manifest.modules
120
+ .flatMap((m) => m.declarations)
121
+ .find((d) => d.tagName === args.tag);
122
+
123
+ if (!match) {
124
+ return { error: `Component <${args.tag}> not found in manifest.` };
125
+ }
126
+ return match;
127
+ }
128
+
129
+ if (name === 'list_tokens') {
130
+ const category = args?.category || 'all';
131
+ if (category === 'all') {
132
+ return tokens;
133
+ }
134
+ return tokens[category] || { error: `Category '${category}' not found.` };
135
+ }
136
+
137
+ if (name === 'generate_snippet') {
138
+ const { tag, variant, size, label, disabled } = args;
139
+ const attrs = [];
140
+ if (variant) attrs.push(`variant="${variant}"`);
141
+ if (size) attrs.push(`size="${size}"`);
142
+ if (disabled) attrs.push('disabled');
143
+
144
+ const attrStr = attrs.length > 0 ? ' ' + attrs.join(' ') : '';
145
+ const content = label || '';
146
+ return {
147
+ snippet: `<${tag}${attrStr}>${content}</${tag}>`,
148
+ };
149
+ }
150
+
151
+ if (name === 'scaffold_component') {
152
+ const tag = args.tag.toLowerCase();
153
+ const className =
154
+ args.name ||
155
+ tag
156
+ .split('-')
157
+ .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
158
+ .join('');
159
+ const formAssociated = !!args.formAssociated;
160
+ const attrs = args.attributes || ['disabled', 'size'];
161
+ const observed = attrs.map((a) => `'${a}'`).join(', ');
162
+
163
+ const signalDefs = attrs
164
+ .map((a) => {
165
+ if (a === 'disabled') return ` disabled = signal(false);`;
166
+ if (a === 'size') return ` size = signal('md'); // 'sm' | 'md' | 'lg'`;
167
+ return ` ${a} = signal('');`;
168
+ })
169
+ .join('\n');
170
+
171
+ const formAssocCode = formAssociated ? ` static formAssociated = true;\n` : '';
172
+ const formCallbacks = formAssociated
173
+ ? `
174
+ connected() {
175
+ this.setFormValue(this.value?.value || '');
176
+ this.validate?.();
177
+ }
178
+
179
+ formReset() {
180
+ this.value.value = this.getAttribute('value') || '';
181
+ this.setFormValue(this.value.value);
182
+ this.validate?.();
183
+ }
184
+
185
+ validate() {
186
+ this.setValidity({});
187
+ return true;
188
+ }
189
+ `
190
+ : '';
191
+
192
+ const code = `import { Elementum } from '../elementum.js';
193
+ import { html, css } from '../template.js';
194
+ import { signal } from '../signal.js';
195
+
196
+ /**
197
+ * ${args.description || `${className} component`}
198
+ */
199
+ export class ${className} extends Elementum {
200
+ ${formAssocCode} static observedAttributes = [${observed}];
201
+
202
+ ${signalDefs}
203
+ ${formCallbacks}
204
+ static styles = css\`
205
+ :host {
206
+ display: inline-block;
207
+ box-sizing: border-box;
208
+ font-family: var(--el-font-sans, system-ui, sans-serif);
209
+ }
210
+
211
+ :host(:focus-visible) {
212
+ outline: 2px solid var(--el-color-primary, #2563eb);
213
+ outline-offset: 2px;
214
+ }
215
+
216
+ .container {
217
+ display: flex;
218
+ align-items: center;
219
+ padding: var(--el-spacing-sm, 8px) var(--el-spacing-md, 16px);
220
+ border-radius: var(--el-radius-md, 8px);
221
+ background: var(--el-surface-card, #ffffff);
222
+ border: 1px solid var(--el-surface-border, #e5e7eb);
223
+ }
224
+ \`;
225
+
226
+ render() {
227
+ return html\`
228
+ <div class="container" part="container">
229
+ <slot></slot>
230
+ </div>
231
+ \`;
232
+ }
233
+ }
234
+
235
+ if (typeof customElements !== 'undefined' && !customElements.get('${tag}')) {
236
+ customElements.define('${tag}', ${className});
237
+ }
238
+ `;
239
+ return {
240
+ tag,
241
+ className,
242
+ code,
243
+ };
244
+ }
245
+
246
+ if (name === 'validate_accessibility') {
247
+ const markup = args.markup || '';
248
+ const violations = [];
249
+ const warnings = [];
250
+ const passed = [];
251
+
252
+ // WCAG 4.1.2: Form elements must have accessible labels
253
+ const inputMatches = markup.match(/<el-input[^>]*>/gi) || [];
254
+ for (const match of inputMatches) {
255
+ const hasAriaLabel = /aria-label=/i.test(match);
256
+ const hasAriaLabelledby = /aria-labelledby=/i.test(match);
257
+ const hasId = /id=["']([^"']+)["']/i.test(match);
258
+ if (!hasAriaLabel && !hasAriaLabelledby && !hasId) {
259
+ violations.push({
260
+ criterion: 'WCAG 4.1.2 (Name, Role, Value)',
261
+ element: match,
262
+ message:
263
+ '<el-input> is missing an accessible name. Provide an aria-label, aria-labelledby, or an id associated with a <label for="...">.',
264
+ });
265
+ } else {
266
+ passed.push({
267
+ criterion: 'WCAG 4.1.2',
268
+ message: '<el-input> has accessible label attributes.',
269
+ });
270
+ }
271
+ }
272
+
273
+ // WCAG 4.1.2 / 1.1.1: Icon buttons or buttons with missing label
274
+ const buttonMatches = markup.match(/<el-button[^>]*>([\s\S]*?)<\/el-button>/gi) || [];
275
+ for (const match of buttonMatches) {
276
+ const tagOpen = match.match(/<el-button[^>]*>/i)?.[0] || '';
277
+ const textContent = match.replace(/<[^>]+>/g, '').trim();
278
+ const hasAriaLabel = /aria-label=/i.test(tagOpen);
279
+ if (!textContent && !hasAriaLabel) {
280
+ violations.push({
281
+ criterion: 'WCAG 1.1.1 (Non-text Content) / WCAG 4.1.2 (Name, Role, Value)',
282
+ element: tagOpen,
283
+ message: '<el-button> has no text content and is missing an aria-label.',
284
+ });
285
+ } else {
286
+ passed.push({
287
+ criterion: 'WCAG 4.1.2',
288
+ message: '<el-button> has accessible text or aria-label.',
289
+ });
290
+ }
291
+ }
292
+
293
+ // WCAG 1.1.1: Image without alt
294
+ const imgMatches = markup.match(/<img[^>]*>/gi) || [];
295
+ for (const match of imgMatches) {
296
+ if (!/alt=/i.test(match)) {
297
+ violations.push({
298
+ criterion: 'WCAG 1.1.1 (Non-text Content)',
299
+ element: match,
300
+ message: '<img> is missing an alt attribute. Provide descriptive alt text or alt="" for decorative images.',
301
+ });
302
+ }
303
+ }
304
+
305
+ // WCAG 2.5.8: Target Size Minimum (24x24px) / Text size
306
+ if (/font-size:\s*([0-9]+)px/i.test(markup)) {
307
+ const sizeMatch = markup.match(/font-size:\s*([0-9]+)px/i);
308
+ if (sizeMatch && Number(sizeMatch[1]) < 12) {
309
+ warnings.push({
310
+ criterion: 'WCAG 1.4.4 (Resize text)',
311
+ message: `Text size ${sizeMatch[1]}px may be too small for readability. Recommend >= 12px.`,
312
+ });
313
+ }
314
+ }
315
+
316
+ // WCAG 3.3.1: Error identification
317
+ if (
318
+ /aria-invalid="true"/i.test(markup) &&
319
+ !/aria-describedby=/i.test(markup) &&
320
+ !/aria-errormessage=/i.test(markup)
321
+ ) {
322
+ warnings.push({
323
+ criterion: 'WCAG 3.3.1 (Error Identification)',
324
+ message:
325
+ 'Element has aria-invalid="true" but lacks aria-describedby or aria-errormessage linking to the validation error explanation.',
326
+ });
327
+ }
328
+
329
+ return {
330
+ valid: violations.length === 0,
331
+ violationsCount: violations.length,
332
+ warningsCount: warnings.length,
333
+ violations,
334
+ warnings,
335
+ passed,
336
+ };
337
+ }
338
+
339
+ throw new Error(`Unknown tool: ${name}`);
340
+ }
341
+
342
+ // JSON-RPC stdio protocol loop
343
+ const rl = readline.createInterface({
344
+ input: process.stdin,
345
+ output: process.stdout,
346
+ terminal: false,
347
+ });
348
+
349
+ rl.on('line', (line) => {
350
+ if (!line.trim()) return;
351
+
352
+ try {
353
+ const request = JSON.parse(line);
354
+
355
+ if (request.method === 'tools/list') {
356
+ const response = {
357
+ jsonrpc: '2.0',
358
+ id: request.id,
359
+ result: { tools: TOOLS },
360
+ };
361
+ process.stdout.write(JSON.stringify(response) + '\n');
362
+ return;
363
+ }
364
+
365
+ if (request.method === 'tools/call') {
366
+ const { name, arguments: toolArgs } = request.params;
367
+ const result = handleToolCall(name, toolArgs);
368
+ const response = {
369
+ jsonrpc: '2.0',
370
+ id: request.id,
371
+ result: {
372
+ content: [
373
+ {
374
+ type: 'text',
375
+ text: JSON.stringify(result, null, 2),
376
+ },
377
+ ],
378
+ },
379
+ };
380
+ process.stdout.write(JSON.stringify(response) + '\n');
381
+ return;
382
+ }
383
+
384
+ if (request.method === 'initialize') {
385
+ const response = {
386
+ jsonrpc: '2.0',
387
+ id: request.id,
388
+ result: {
389
+ protocolVersion: '2024-11-05',
390
+ capabilities: { tools: {} },
391
+ serverInfo: {
392
+ name: 'elementum-design-system-mcp',
393
+ version: '0.1.0',
394
+ },
395
+ },
396
+ };
397
+ process.stdout.write(JSON.stringify(response) + '\n');
398
+ return;
399
+ }
400
+ } catch (err) {
401
+ const errorResponse = {
402
+ jsonrpc: '2.0',
403
+ id: null,
404
+ error: { code: -32603, message: err.message },
405
+ };
406
+ process.stdout.write(JSON.stringify(errorResponse) + '\n');
407
+ }
408
+ });
package/package.json CHANGED
@@ -1,6 +1,74 @@
1
1
  {
2
2
  "name": "@wcomp/elementum",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Ultra-lightweight, signal-driven, frameworkless Web Components for modern design systems",
5
+ "type": "module",
6
+ "main": "./src/index.js",
7
+ "types": "./src/index.d.ts",
8
+ "bin": {
9
+ "elementum-mcp": "./mcp/server.js"
10
+ },
11
+ "publishConfig": {
12
+ "access": "public"
13
+ },
14
+ "files": [
15
+ "src",
16
+ "custom-elements.json",
17
+ "tokens",
18
+ "mcp",
19
+ "skills",
20
+ "LICENSE",
21
+ "README.md"
22
+ ],
23
+ "exports": {
24
+ ".": {
25
+ "types": "./src/index.d.ts",
26
+ "default": "./src/index.js"
27
+ },
28
+ "./ssr": "./src/ssr.js",
29
+ "./ag-ui": "./src/ag-ui.js",
30
+ "./tokens.css": "./src/tokens.css",
31
+ "./custom-elements.json": "./custom-elements.json",
32
+ "./components/*": "./src/components/*.js"
33
+ },
34
+ "homepage": "https://elementum-sage.vercel.app/",
35
+ "repository": {
36
+ "type": "git",
37
+ "url": "git+https://github.com/pinguxx/Elementum.git"
38
+ },
39
+ "bugs": {
40
+ "url": "https://github.com/pinguxx/Elementum/issues"
41
+ },
42
+ "scripts": {
43
+ "test": "node --test --experimental-test-coverage",
44
+ "serve": "node tools/serve.js",
45
+ "serve:proxy": "node tools/serve.js --proxy",
46
+ "ssr": "node examples/ssr-server.js",
47
+ "ssr:static": "node examples/ssr-server.js --static examples/ssr-demo.html",
48
+ "mcp": "node mcp/server.js",
49
+ "create": "node tools/create-component.js",
50
+ "tokens:sync": "node tools/sync-tokens.js",
51
+ "catalog:diff": "node tools/audit-catalog-diff.js",
52
+ "penpot:mcp": "node tools/sync-penpot-mcp.js",
53
+ "penpot:design-app": "node tools/design-ledgerflow-penpot.js",
54
+ "penpot:generate": "node tools/penpot-to-elementum.js"
55
+ },
56
+ "keywords": [
57
+ "web-components",
58
+ "custom-elements",
59
+ "signals",
60
+ "shadow-dom",
61
+ "declarative-shadow-dom",
62
+ "ssr",
63
+ "design-system",
64
+ "figma",
65
+ "penpot",
66
+ "mcp",
67
+ "ai-ui"
68
+ ],
69
+ "author": "wcomp",
70
+ "license": "MIT",
71
+ "devDependencies": {
72
+ "happy-dom": "^21.0.4"
73
+ }
74
+ }
@@ -0,0 +1,11 @@
1
+ # Break-UI Failure Vector Checklist
2
+
3
+ | Vector | What to Try | Expected Resilience |
4
+ | :--- | :--- | :--- |
5
+ | **320px Mobile** | Narrow viewport on navbar, tables, segmented controls, dialogs | Zero horizontal body scroll; navbar collapses cleanly; tables scroll internally. |
6
+ | **Dark Mode Hover** | Hover secondary, ghost, and canvas-toggle buttons in dark mode | High-contrast text and surface tokens remain legible (never white-on-light-gray). |
7
+ | **Long Unbroken Text** | Pass 100-char label into `<el-button>`, `<el-chip>`, `<el-badge>`, `<el-card>` | Graceful truncation or wrapping without breaking sibling alignment. |
8
+ | **Empty / Null Data** | Pass `data="[]"`, `options=""`, or omit slotted children | Renders fallback `label` attribute or `<el-empty-state>` without throwing. |
9
+ | **Keyboard Only** | Operate `<el-command>`, `<el-tabs>`, `<el-dropdown>`, `<el-select>`, `<el-dialog>` with keyboard | Full arrow navigation, Enter/Space activation, Escape close, and focus restoration. |
10
+ | **Form Reset** | Mutate `<el-input>`, `<el-switch>`, `<el-select>`, `<el-slider>` then call `form.reset()` | Restores initial HTML default attributes cleanly via `formReset()`. |
11
+ | **Mount / Unmount Churn** | Append and remove component 20× in a loop | Zero memory/listener leaks (`this.signal` `AbortController` cleans up all listeners). |
@@ -0,0 +1,16 @@
1
+ ---
2
+ name: elementum-break-ui
3
+ description: Adversarial UI stress-testing skill for Web Components and Elementum pages. Systematically attempts to break layout, contrast, responsiveness, focus management, and reactivity before shipping.
4
+ ---
5
+
6
+ # Elementum Break-UI Stress-Test Skill
7
+
8
+ Before declaring a component or page "done", actively try to break it across every vector in [CATALOG.md](./CATALOG.md).
9
+
10
+ ## Stress-Test Workflow
11
+ 1. **Viewport & Overflow**: Resize to `320px`, `375px`, `768px`, and `1440px`. Verify zero horizontal page overflow (`document.documentElement.scrollWidth <= window.innerWidth`), responsive `<el-navbar>` collapse, and scrollable `<el-table>` containers.
12
+ 2. **Dark Mode & Contrast**: Toggle `:root[data-theme="dark"]` and hover/focus every button, badge, toggle, tooltip, and input. Confirm WCAG 2.2 AA contrast (≥ 4.5:1 for text, ≥ 3:1 for UI controls) and ensure isolated preview canvases stay independent of page theme.
13
+ 3. **Extreme Content**: Test empty states (`""`, `[]`), 1-character labels, 120-character unbroken strings, and 50+ list items. Verify avatars never squish (`flex-shrink: 0`) and numbers never jitter (`tabular-nums`).
14
+ 4. **Keyboard & Focus**: Tab through the entire flow without a mouse. Verify `<el-dialog>` and `<el-drawer>` restore focus on close, `Escape` dismisses overlays, and roving `tabindex` works on `<el-tabs>`, `<el-toolbar>`, `<el-menubar>`, and `<el-radio-group>`.
15
+ 5. **Rapid & Edge Interactions**: Double-click submit buttons, open/close drawers rapidly, toggle `disabled` mid-interaction, and verify zero uncaught console errors or leaked listeners after element removal (`disconnected()`).
16
+ 6. **Automated Gates**: Run `npm test` (including `test/catalog-contract.test.js` and `test/craft-contract.test.js`) and `node --test test/pages-smoke.test.js`.
@@ -0,0 +1,18 @@
1
+ ---
2
+ name: elementum-mobile
3
+ description: Mobile-native CSS and interaction standards for @wcomp/elementum Web Components — preventing sticky hover states, tap highlight flashes, iOS input auto-zoom, 100vh clipping, and background scroll bleed.
4
+ ---
5
+
6
+ # Elementum Mobile-Native Craft Skill
7
+
8
+ Use this skill when building or auditing mobile views, PWAs, bottom sheets, or touch interactions with Elementum Web Components.
9
+
10
+ ## Mobile-Native Checklist
11
+ 1. **Eliminate Tap Delay & Grey Flash**: Set `touch-action: manipulation` and `-webkit-tap-highlight-color: transparent` on interactive buttons, toggles, chips, and segmented controls.
12
+ 2. **Prevent Sticky Touch Hover**: Guard decorative `:hover` effects with `@media (hover: hover) and (pointer: fine)` when hover states would otherwise stick after a tap.
13
+ 3. **Prevent iOS Safari Input Auto-Zoom**: Inside `@media (pointer: coarse)`, ensure `input`, `select`, and `textarea` use `font-size: max(16px, 1em)` so focusing a field never zooms the page.
14
+ 4. **Use Dynamic Viewport (`100dvh`) + Safe Areas**: Never rely on bare `100vh` for sheets or modals—pair with `100dvh` and `env(safe-area-inset-bottom, 0px)` so iOS home indicators and dynamic toolbars never obscure controls.
15
+ 5. **Contain Overlay Scroll**: Set `overscroll-behavior: contain` on `<el-drawer>`, `<el-dialog>`, and scrollable menus so scrolling inside an overlay never triggers pull-to-refresh or scrolls the background page.
16
+ 6. **Prevent Accidental Text Selection**: Keep `user-select: none` on buttons, tabs, and drag handles so long-pressing doesn't highlight UI labels.
17
+
18
+ These rules are automatically enforced by `test/craft-contract.test.js`.
@@ -0,0 +1,18 @@
1
+ ---
2
+ name: elementum-motion
3
+ description: Author, audit, and refine CSS animations, micro-interactions, and motion physics in Shadow DOM Web Components. Use when adding transitions, reviewing motion diffs, or removing sluggish/unnecessary animations.
4
+ ---
5
+
6
+ # Elementum Motion & Craft Skill
7
+
8
+ High-craft UI motion feels crisp, physical, and unobtrusive. Follow [STANDARDS.md](./STANDARDS.md) whenever authoring or reviewing Shadow DOM component CSS.
9
+
10
+ ## Quick Rules
11
+ 1. **Never use `transition: all`**: Explicitly list transitioned properties (`transform`, `opacity`, `background-color`, `border-color`, `box-shadow`).
12
+ 2. **Choose the Right Easing & Duration**:
13
+ - Entrances & popovers: `ease-out` or `--el-ease-out-expo` (`cubic-bezier(0.16, 1, 0.3, 1)`), **120ms–250ms** (never `ease-in` on entrances).
14
+ - Micro-feedback (`:active` press): **100ms–150ms** with `transform: scale(0.97)`.
15
+ 3. **Origin-Aware Overlays**: Popovers, dropdowns, tooltips, and context menus scale from their trigger edge (`transform-origin: bottom center` when placed `top`, `top center` when `bottom`, etc.). Modals (`<el-dialog>`) stay centered.
16
+ 4. **Compositor-Only Motion**: Animate `transform` and `opacity` (and keep animated `blur()` ≤ `20px`). Avoid animating `width`, `height`, `top`, or `left` on high-frequency interactions.
17
+ 5. **Respect Reduced Motion**: Every component with `@keyframes` or transform transitions must include `@media (prefers-reduced-motion: reduce)` to disable or calm animations.
18
+ 6. **Know What NOT to Animate**: Keep keyboard-driven interactions (`<el-command>` `⌘K` selection, `<el-tabs>` arrow switching, table row focus) snappy and instant—motion should clarify spatial changes, never delay power users.
@@ -0,0 +1,15 @@
1
+ # Elementum Motion & UI Craft Standards
2
+
3
+ | Problem | Elementum Standard |
4
+ | :--- | :--- |
5
+ | Random properties animate or stutter | Ban `transition: all`; list exact properties (`transform`, `opacity`, `background-color`, `border-color`). |
6
+ | Buttons / toggles feel unresponsive | Apply `transform: scale(0.97)` on `:active:not(:disabled)` (reset under `prefers-reduced-motion`). |
7
+ | Dropdowns / tooltips feel sluggish | Use `ease-out` / `var(--el-ease-out-expo)` under `250ms`; never use `ease-in` for entrances. |
8
+ | Popover grows from wrong spot | Set `transform-origin` toward the trigger edge (modals remain centered). |
9
+ | Avatars squish in flex containers | Always set `flex-shrink: 0` on `:host` in `<el-avatar>`. |
10
+ | Numbers jitter during live updates | Set `font-variant-numeric: tabular-nums` on `<el-number-flow>`, `<el-number-field>`, `<el-meter>`, `<el-progress>`, `<el-pagination>`, and `<el-table>`. |
11
+ | Motion causes vestibular discomfort | Guard every `@keyframes` and transform transition with `@media (prefers-reduced-motion: reduce)`. |
12
+ | Long prose lines fatigue readers | Constrain body paragraphs with `max-width: 65ch` and tighten large headings (`letter-spacing: -0.02em`). |
13
+ | Flat 1px opaque borders look generic | Prefer `--el-border-translucent` (`rgba(15, 23, 42, 0.08)`) paired with layered ambient `--el-shadow-card`. |
14
+
15
+ These rules are enforced automatically in CI by `test/craft-contract.test.js`.
@@ -0,0 +1,45 @@
1
+ ---
2
+ name: elementum-penpot
3
+ description: Bidirectional Penpot MCP design system workflow for Elementum — syncing W3C DTCG tokens, 165 component variants into Penpot, and generating live Web Components apps from Penpot pages.
4
+ ---
5
+
6
+ # Elementum Penpot MCP Skill
7
+
8
+ Use this skill when syncing Elementum's design system into [Penpot](https://design.penpot.app) or generating live Elementum Web Components apps from a Penpot design file.
9
+
10
+ ## Security First
11
+ - **Never** hardcode, log, or commit a user's personal `userToken` JWT into source control or docs.
12
+ - Always pass it via `PENPOT_MCP_URL`, `PENPOT_MCP_TOKEN`, or runtime `--url` / `--token` CLI flags.
13
+ - Only publish Penpot's read-only viewer share URLs (`https://design.penpot.app/?screen=viewer&...&share-id=...`) in public docs.
14
+
15
+ ## Workflows
16
+
17
+ ### 1. Code → Penpot Design System (`npm run penpot:mcp`)
18
+ Generates 54 W3C DTCG tokens (`Elementum Core`, `Elementum Light`, `Elementum Dark`), 28 library colors, `00 · Foundations`, and 8 category pages (`01 · Actions & Buttons` .. `08 · AI & Specialist`) with 165 Master Component variants:
19
+ ```bash
20
+ npm run penpot:mcp -- --url "https://design.penpot.app/mcp/stream?userToken=<YOUR_TOKEN>"
21
+ # Validate locally without network:
22
+ npm run penpot:mcp -- --dry-run
23
+ ```
24
+
25
+ ### 2. Penpot → Live Elementum App (`npm run penpot:generate`)
26
+ Name Penpot component boards using `el-*` annotations (e.g., `el-navbar | brand="LedgerFlow" badge="Finance"`), then extract the Penpot tree, validate tags against Elementum's catalog, export a PNG mockup, and generate a working zero-dependency HTML app:
27
+ ```bash
28
+ npm run penpot:generate -- \
29
+ --url "https://design.penpot.app/mcp/stream?userToken=<YOUR_TOKEN>" \
30
+ --page "LedgerFlow App" \
31
+ --out examples/ledgerflow.html \
32
+ --export-png docs/assets/ledgerflow-penpot.png
33
+ ```
34
+
35
+ ### 3. Penpot → CSS Tokens (`npm run tokens:sync`)
36
+ Export W3C DTCG JSON from Penpot to `tokens/penpot-tokens.json` and compile to `src/tokens.css`:
37
+ ```bash
38
+ npm run tokens:sync tokens/penpot-tokens.json
39
+ ```
40
+
41
+ ## Penpot API Gotchas
42
+ - `penpot.createPage()` takes **0 arguments**; assign `page.name = '...'` and `await penpot.openPage(page)` before creating shapes.
43
+ - Penpot's default font supports weights `200, 300, 400, 600, 700, 900` (not `500`).
44
+ - Use uppercase 6-digit hex strings (`#2563EB`) for `fills`, `strokes`, and `LibraryColor.color`.
45
+ - Keep the Penpot browser tab active/visible so Chrome does not throttle the Penpot MCP Plugin heartbeat.
@@ -0,0 +1,14 @@
1
+ # Elementum Component Quick Catalog (8 Categories · 105 Elements)
2
+
3
+ | Category | Key Components |
4
+ | :--- | :--- |
5
+ | **Actions & Buttons** | `<el-button>`, `<el-toggle>`, `<el-toggle-group>`, `<el-segmented-control>`, `<el-toolbar>` |
6
+ | **Forms & Inputs** | `<el-input>`, `<el-textarea>`, `<el-select>`, `<el-autocomplete>`, `<el-checkbox>`, `<el-checkbox-card>`, `<el-radio>`, `<el-radio-group>`, `<el-radio-card>`, `<el-switch>`, `<el-slider>`, `<el-number-field>`, `<el-otp-input>`, `<el-rating>`, `<el-calendar>`, `<el-datepicker>`, `<el-dropzone>`, `<el-field>`, `<el-form>` |
7
+ | **Data Display** | `<el-card>`, `<el-table>`, `<el-chart>`, `<el-badge>`, `<el-chip>`, `<el-avatar>`, `<el-avatar-group>`, `<el-accordion>`, `<el-timeline>`, `<el-tree-view>`, `<el-data-list>`, `<el-code-block>`, `<el-kbd>`, `<el-number-flow>`, `<el-carousel>`, `<el-empty-state>` |
8
+ | **Feedback & Status** | `<el-alert>`, `<el-callout>`, `<el-toast>` / `<el-toaster>`, `<el-progress>`, `<el-meter>`, `<el-spinner>`, `<el-skeleton>` |
9
+ | **Overlays & Dialogs** | `<el-dialog>`, `<el-alert-dialog>`, `<el-drawer>`, `<el-dropdown>`, `<el-popover>`, `<el-tooltip>`, `<el-command>`, `<el-context-menu>`, `<el-preview-card>` |
10
+ | **Navigation** | `<el-navbar>`, `<el-sidebar>`, `<el-tabs>`, `<el-tab>`, `<el-breadcrumb>`, `<el-pagination>`, `<el-menubar>`, `<el-navigation-menu>`, `<el-router>`, `<el-route>`, `<el-route-link>` |
11
+ | **Layout & Primitives** | `<el-separator>`, `<el-resizable>`, `<el-scroll-area>`, `<el-aspect-ratio>`, `<el-collapsible>`, `<el-inset>`, `<el-visually-hidden>`, `<el-theme-switch>` |
12
+ | **AI & Specialist** | `<el-prompt-input>`, `<el-reasoning-card>`, `<el-streaming-text>`, `<el-tool-call>`, `<el-border-beam>` |
13
+
14
+ For full attribute, slot, event, and CSS `::part()` schemas, query `mcp/server.js` (`get_component_doc`) or inspect `custom-elements.json`.
@@ -0,0 +1,21 @@
1
+ ---
2
+ name: elementum-ui
3
+ description: Compose accessible, zero-dependency user interfaces using @wcomp/elementum's 105 Web Components, micro-signals, and Form-Associated Custom Elements (FACE). Use when building or refactoring UI with Elementum.
4
+ ---
5
+
6
+ # Elementum UI Engineering Skill
7
+
8
+ Use `@wcomp/elementum` primitives directly—do **not** reach for React, Tailwind utility walls, or hand-rolled `<div>` modals/inputs when an Elementum Custom Element exists.
9
+
10
+ ## Core Rules
11
+ 1. **Zero Runtime Dependencies**: Import `@wcomp/elementum` and `@wcomp/elementum/tokens.css` via native ES modules (`<script type="module">`).
12
+ 2. **Verify Schema Before Writing Markup**: Read [CATALOG.md](./CATALOG.md) or query the Elementum MCP server (`list_components`, `get_component_doc`) so you never invent nonexistent attributes or slots.
13
+ 3. **Reactive Signal Bindings**:
14
+ - Inside `html` tagged templates, pass either the signal object (`${this.count}`) or a closure (`${() => this.count.value}`).
15
+ - **Never** evaluate `${this.count.value}` directly outside an arrow function—it unwraps once at mount and stops updating.
16
+ - Use `.prop=${...}` for JS properties, `?attr=${...}` for boolean attributes, and `@event=${...}` for listeners.
17
+ 4. **Native Form Participation (FACE)**: Place `<el-input>`, `<el-select>`, `<el-textarea>`, `<el-checkbox>`, `<el-radio-group>`, `<el-switch>`, `<el-slider>`, `<el-datepicker>`, `<el-otp-input>`, `<el-autocomplete>`, and `<el-segmented-control>` inside native `<form>` elements—they integrate with `FormData`, `reportValidity()`, and `form.reset()`.
18
+ 5. **Theming & Contrast**:
19
+ - Use `--el-*` CSS custom properties (`--el-surface-base`, `--el-surface-card`, `--el-text-primary`, `--el-border-translucent`, `--el-shadow-card`) rather than hardcoded hex colors.
20
+ - Always test both Light (`:root`) and Dark (`:root[data-theme="dark"]`) modes, especially hover states on secondary/ghost controls.
21
+ 6. **Agentic / AG-UI Frontends**: Use `createAgUiStore()` + `<el-prompt-input>`, `<el-reasoning-card>`, `<el-streaming-text>`, `<el-tool-call>` (HITL approval), and `<el-number-flow>` to bind live SSE agent streams directly to DOM nodes without virtual-DOM re-render cascades.