@chotot/clad-ui 3.0.0-next.2 → 3.0.0-next.3
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/README.md +42 -0
- package/ai/clad-ui-helper.js +267 -0
- package/ai/knowledge-base/README.md +154 -0
- package/ai/knowledge-base/clad-ui-database.json +9378 -0
- package/ai/knowledge-base/component-categories.json +616 -0
- package/ai/knowledge-base/components/metadata/charts-axis.json +31 -0
- package/ai/knowledge-base/components/metadata/charts-barchart.json +57 -0
- package/ai/knowledge-base/components/metadata/charts-basechart.tsx.json +31 -0
- package/ai/knowledge-base/components/metadata/charts-chartshared.json +31 -0
- package/ai/knowledge-base/components/metadata/charts-linechart.json +189 -0
- package/ai/knowledge-base/components/metadata/charts-piechart.json +57 -0
- package/ai/knowledge-base/components/metadata/components-announcer.json +215 -0
- package/ai/knowledge-base/components/metadata/components-badge.json +168 -0
- package/ai/knowledge-base/components/metadata/components-box.json +348 -0
- package/ai/knowledge-base/components/metadata/components-breadcrumbs.json +75 -0
- package/ai/knowledge-base/components/metadata/components-button.json +187 -0
- package/ai/knowledge-base/components/metadata/components-checkbox.json +161 -0
- package/ai/knowledge-base/components/metadata/components-chip.json +266 -0
- package/ai/knowledge-base/components/metadata/components-currencyinput.json +136 -0
- package/ai/knowledge-base/components/metadata/components-datepicker.json +87 -0
- package/ai/knowledge-base/components/metadata/components-dropdown.json +282 -0
- package/ai/knowledge-base/components/metadata/components-grid.json +92 -0
- package/ai/knowledge-base/components/metadata/components-input.json +432 -0
- package/ai/knowledge-base/components/metadata/components-pagination.json +111 -0
- package/ai/knowledge-base/components/metadata/components-popover.json +63 -0
- package/ai/knowledge-base/components/metadata/components-radiobutton.json +170 -0
- package/ai/knowledge-base/components/metadata/components-rowitem.json +281 -0
- package/ai/knowledge-base/components/metadata/components-shapeicon.json +139 -0
- package/ai/knowledge-base/components/metadata/components-slider.json +177 -0
- package/ai/knowledge-base/components/metadata/components-snack.json +181 -0
- package/ai/knowledge-base/components/metadata/components-tabs.json +169 -0
- package/ai/knowledge-base/components/metadata/components-textarea.json +285 -0
- package/ai/knowledge-base/components/metadata/components-textlabel.json +129 -0
- package/ai/knowledge-base/components/metadata/components-toggleswitch.json +134 -0
- package/ai/knowledge-base/components/metadata/components-tooltip.json +291 -0
- package/ai/knowledge-base/components/metadata/patterns-drawer.json +310 -0
- package/ai/knowledge-base/components/metadata/patterns-emptystate.json +106 -0
- package/ai/knowledge-base/components/metadata/patterns-inputgroup.json +105 -0
- package/ai/knowledge-base/components/metadata/patterns-legacydialog.json +177 -0
- package/ai/knowledge-base/components/metadata/patterns-legacypopup.json +236 -0
- package/ai/knowledge-base/components/metadata/patterns-multisearchdropdown.json +249 -0
- package/ai/knowledge-base/components/metadata/patterns-popup.json +268 -0
- package/ai/knowledge-base/components/metadata/patterns-rangeinput.json +105 -0
- package/ai/knowledge-base/components/metadata/patterns-searchbar.json +150 -0
- package/ai/knowledge-base/components/metadata/patterns-searchinput.json +312 -0
- package/ai/knowledge-base/components/metadata/patterns-tagcloud.json +244 -0
- package/ai/knowledge-base/components/metadata/summaries.json +610 -0
- package/ai/knowledge-base/design-tokens/tokens.json +483 -0
- package/ai/knowledge-base/patterns/documentation.json +131 -0
- package/ai/knowledge-base/prompts/common-system-prompt.md +592 -0
- package/ai/knowledge-base/prompts/figma-system-prompt.md +396 -0
- package/ai/knowledge-base/search-index/icons/asset-icons.json +1 -0
- package/ai/knowledge-base/search-index/icons/collection.json +5 -0
- package/ai/knowledge-base/search-index/icons/system-icons.json +1 -0
- package/ai/knowledge-base/search-index/search-index.json +899 -0
- package/ai/knowledge-base/validation-rules/component-rules.json +658 -0
- package/ai/skill/SKILL.md +103 -0
- package/dist/clad-ui.es.js +25 -25
- package/package.json +8 -2
package/README.md
CHANGED
|
@@ -111,6 +111,48 @@ Maintaining the system:
|
|
|
111
111
|
|
|
112
112
|
Refer to [Overview > Getting-started document](https://clad-ui.chotot.org/?path=/docs/overview-getting-started--page).
|
|
113
113
|
|
|
114
|
+
## Claude Code / AI skill
|
|
115
|
+
|
|
116
|
+
`clad-ui` ships with a Claude Code skill that gives Claude direct access to components, icons, tokens, and implementation guidelines — no MCP server required.
|
|
117
|
+
|
|
118
|
+
### Automatic install (npm)
|
|
119
|
+
|
|
120
|
+
The skill is linked automatically when you install the package:
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
pnpm install @chotot/clad-ui
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Manual setup (pnpm)
|
|
127
|
+
|
|
128
|
+
pnpm caches lifecycle scripts per package version. Add this to your project's `package.json` so the skill re-links on every install:
|
|
129
|
+
|
|
130
|
+
```json
|
|
131
|
+
{
|
|
132
|
+
"scripts": {
|
|
133
|
+
"postinstall": "npx clad-ui-helper link-skill"
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Then run `pnpm install`.
|
|
139
|
+
|
|
140
|
+
### Usage in Claude Code
|
|
141
|
+
|
|
142
|
+
Once installed, use the `/clad-ui` skill in any Claude Code session:
|
|
143
|
+
|
|
144
|
+
| Command | Description |
|
|
145
|
+
|---|---|
|
|
146
|
+
| `/clad-ui search <query>` | Find components by name or description |
|
|
147
|
+
| `/clad-ui info <Name>` | Full component detail: props, examples, import path |
|
|
148
|
+
| `/clad-ui icons [query]` | Search or list icons |
|
|
149
|
+
| `/clad-ui tokens [category]` | Browse design tokens |
|
|
150
|
+
| `/clad-ui validate <Name> [props]` | Validate component usage |
|
|
151
|
+
| `/clad-ui stats` | Design system overview |
|
|
152
|
+
| `/clad-ui guidelines` | Load the full system prompt |
|
|
153
|
+
|
|
154
|
+
You can also describe a UI task without a subcommand and the skill will find relevant components automatically.
|
|
155
|
+
|
|
114
156
|
## Verifying clad-ui components in production
|
|
115
157
|
|
|
116
158
|
Open browser Devtool (F12) and add following CSS to the `:root` element:
|
|
@@ -0,0 +1,267 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// clad-ui-helper.js — single entrypoint for all Clad UI skill queries and installation
|
|
3
|
+
//
|
|
4
|
+
// Usage: node clad-ui-helper.js <command> [args] [--flag=value]
|
|
5
|
+
//
|
|
6
|
+
// Commands:
|
|
7
|
+
// link-skill — symlink .claude/skills/clad-ui into the current project
|
|
8
|
+
// search [query] [--category=components|patterns|charts] [--status=stable|beta|deprecated]
|
|
9
|
+
// info <ComponentName>
|
|
10
|
+
// icons [query] [--category=system|asset]
|
|
11
|
+
// tokens [colors|typography|spacing|breakpoints|all]
|
|
12
|
+
// validate <ComponentName> [props-json]
|
|
13
|
+
// stats
|
|
14
|
+
|
|
15
|
+
const fs = require('fs');
|
|
16
|
+
const path = require('path');
|
|
17
|
+
|
|
18
|
+
const KB = path.join(__dirname, 'knowledge-base');
|
|
19
|
+
const [, , cmd, ...argv] = process.argv;
|
|
20
|
+
|
|
21
|
+
// Parse flags and positional args
|
|
22
|
+
const flags = {};
|
|
23
|
+
const args = [];
|
|
24
|
+
for (const a of argv) {
|
|
25
|
+
const m = a.match(/^--(\w[\w-]*)=(.+)$/);
|
|
26
|
+
if (m) [,, flags[m[1]]] = m;
|
|
27
|
+
else args.push(a);
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
function readJson(file) {
|
|
31
|
+
return JSON.parse(fs.readFileSync(path.join(KB, file), 'utf8'));
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function out(data) {
|
|
35
|
+
console.log(JSON.stringify(data, null, 2));
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
function scoreComponent(c, q) {
|
|
39
|
+
const name = c.name.toLowerCase();
|
|
40
|
+
const desc = (c.description || '').toLowerCase();
|
|
41
|
+
if (name === q) return 100;
|
|
42
|
+
if (name.startsWith(q)) return 80;
|
|
43
|
+
if (name.includes(q)) return 60;
|
|
44
|
+
if (desc.includes(q)) return 30;
|
|
45
|
+
const words = q.split(/\s+/);
|
|
46
|
+
if (words.every(w => name.includes(w) || desc.includes(w))) return 20;
|
|
47
|
+
return 0;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const commands = {
|
|
51
|
+
|
|
52
|
+
'link-skill': function() {
|
|
53
|
+
const projectRoot = process.env.INIT_CWD || process.cwd();
|
|
54
|
+
const skillSrc = path.join(__dirname, 'skill');
|
|
55
|
+
const skillDest = path.join(projectRoot, '.claude', 'skills', 'clad-ui');
|
|
56
|
+
|
|
57
|
+
if (!fs.existsSync(path.join(skillSrc, 'SKILL.md'))) {
|
|
58
|
+
// ai/skill is only present in published packages, not in local dev installs.
|
|
59
|
+
process.exit(0);
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
try {
|
|
63
|
+
fs.mkdirSync(path.join(projectRoot, '.claude', 'skills'), { recursive: true });
|
|
64
|
+
fs.rmSync(skillDest, { recursive: true, force: true });
|
|
65
|
+
fs.symlinkSync(skillSrc, skillDest, 'dir');
|
|
66
|
+
console.log(`clad-ui: linked .claude/skills/clad-ui → ${skillSrc}`);
|
|
67
|
+
} catch (err) {
|
|
68
|
+
console.warn(`clad-ui: could not link skill (${err.message})`);
|
|
69
|
+
}
|
|
70
|
+
},
|
|
71
|
+
|
|
72
|
+
search() {
|
|
73
|
+
const query = args.join(' ').trim().toLowerCase();
|
|
74
|
+
let results = readJson('components/metadata/summaries.json');
|
|
75
|
+
if (flags.category) results = results.filter(c => c.category === flags.category);
|
|
76
|
+
if (flags.status) results = results.filter(c => c.status === flags.status);
|
|
77
|
+
if (query) {
|
|
78
|
+
results = results
|
|
79
|
+
.map(c => ({ c, s: scoreComponent(c, query) }))
|
|
80
|
+
.filter(({ s }) => s > 0)
|
|
81
|
+
.sort((a, b) => b.s - a.s)
|
|
82
|
+
.map(({ c }) => c);
|
|
83
|
+
}
|
|
84
|
+
out({
|
|
85
|
+
total: results.length,
|
|
86
|
+
results: results.map(c => ({
|
|
87
|
+
id: c.id,
|
|
88
|
+
name: c.name,
|
|
89
|
+
category: c.category,
|
|
90
|
+
status: c.status,
|
|
91
|
+
description: c.description,
|
|
92
|
+
})),
|
|
93
|
+
});
|
|
94
|
+
},
|
|
95
|
+
|
|
96
|
+
info() {
|
|
97
|
+
const name = args[0];
|
|
98
|
+
if (!name) { console.error('Usage: info <ComponentName>'); process.exit(1); }
|
|
99
|
+
|
|
100
|
+
const summaries = readJson('components/metadata/summaries.json');
|
|
101
|
+
const q = name.toLowerCase();
|
|
102
|
+
const component = summaries.find(c => c.name.toLowerCase() === q)
|
|
103
|
+
|| summaries.find(c => c.id.toLowerCase() === q);
|
|
104
|
+
|
|
105
|
+
if (!component) {
|
|
106
|
+
const suggestions = summaries
|
|
107
|
+
.filter(c => c.name.toLowerCase().includes(q))
|
|
108
|
+
.slice(0, 5)
|
|
109
|
+
.map(c => c.name);
|
|
110
|
+
console.error(JSON.stringify({ error: `Component "${name}" not found`, suggestions }));
|
|
111
|
+
process.exit(1);
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
const detailPath = path.join(KB, `components/metadata/${component.id}.json`);
|
|
115
|
+
if (!fs.existsSync(detailPath)) {
|
|
116
|
+
console.error(JSON.stringify({ error: `Detail file missing for "${component.id}"` }));
|
|
117
|
+
process.exit(1);
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
out(JSON.parse(fs.readFileSync(detailPath, 'utf8')));
|
|
121
|
+
},
|
|
122
|
+
|
|
123
|
+
icons() {
|
|
124
|
+
const query = args.join(' ').trim().toLowerCase();
|
|
125
|
+
const collection = readJson('search-index/icons/collection.json');
|
|
126
|
+
let results = [...(collection.system || []), ...(collection.assets || [])];
|
|
127
|
+
|
|
128
|
+
if (flags.category) results = results.filter(i => i.category === flags.category);
|
|
129
|
+
if (query) {
|
|
130
|
+
results = results
|
|
131
|
+
.map(i => {
|
|
132
|
+
const name = i.name.toLowerCase();
|
|
133
|
+
const keywords = (i.keywords || []).join(' ').toLowerCase();
|
|
134
|
+
const desc = (i.description || '').toLowerCase();
|
|
135
|
+
let s = 0;
|
|
136
|
+
if (name === query) s = 100;
|
|
137
|
+
else if (name.startsWith(query)) s = 80;
|
|
138
|
+
else if (name.includes(query)) s = 60;
|
|
139
|
+
else if (keywords.includes(query)) s = 50;
|
|
140
|
+
else if (desc.includes(query)) s = 30;
|
|
141
|
+
return { i, s };
|
|
142
|
+
})
|
|
143
|
+
.filter(({ s }) => s > 0)
|
|
144
|
+
.sort((a, b) => b.s - a.s)
|
|
145
|
+
.map(({ i }) => i);
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
const limit = flags.limit === 'all' ? Infinity : parseInt(flags.limit || '30', 10);
|
|
149
|
+
out({
|
|
150
|
+
total: results.length,
|
|
151
|
+
results: results.slice(0, limit).map(i => ({
|
|
152
|
+
id: i.id,
|
|
153
|
+
name: i.name,
|
|
154
|
+
category: i.category,
|
|
155
|
+
type: i.type,
|
|
156
|
+
hasFilledVariant: i.hasFilledVariant,
|
|
157
|
+
keywords: i.keywords,
|
|
158
|
+
usage: i.usage,
|
|
159
|
+
})),
|
|
160
|
+
});
|
|
161
|
+
},
|
|
162
|
+
|
|
163
|
+
tokens() {
|
|
164
|
+
const category = args[0] || 'all';
|
|
165
|
+
const tokens = readJson('design-tokens/tokens.json');
|
|
166
|
+
const result = category === 'all' ? tokens : tokens[category];
|
|
167
|
+
if (!result) {
|
|
168
|
+
console.error(JSON.stringify({ error: `Unknown category "${category}"`, available: Object.keys(tokens) }));
|
|
169
|
+
process.exit(1);
|
|
170
|
+
}
|
|
171
|
+
out({ category, tokens: result });
|
|
172
|
+
},
|
|
173
|
+
|
|
174
|
+
validate() {
|
|
175
|
+
const name = args[0];
|
|
176
|
+
if (!name) { console.error('Usage: validate <ComponentName> [props-json]'); process.exit(1); }
|
|
177
|
+
|
|
178
|
+
const summaries = readJson('components/metadata/summaries.json');
|
|
179
|
+
const component = summaries.find(c => c.name.toLowerCase() === name.toLowerCase());
|
|
180
|
+
if (!component) {
|
|
181
|
+
const suggestions = summaries
|
|
182
|
+
.filter(c => c.name.toLowerCase().includes(name.toLowerCase()))
|
|
183
|
+
.slice(0, 3).map(c => c.name);
|
|
184
|
+
out({ isValid: false, errors: [`Component "${name}" not found`], suggestions });
|
|
185
|
+
return;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
const detail = JSON.parse(
|
|
189
|
+
fs.readFileSync(path.join(KB, `components/metadata/${component.id}.json`), 'utf8')
|
|
190
|
+
);
|
|
191
|
+
|
|
192
|
+
const errors = [];
|
|
193
|
+
const warnings = [];
|
|
194
|
+
const bestPractices = [];
|
|
195
|
+
const props = args[1] ? JSON.parse(args[1]) : null;
|
|
196
|
+
|
|
197
|
+
if (props) {
|
|
198
|
+
for (const rp of (detail.props || []).filter(p => p.required)) {
|
|
199
|
+
if (!(rp.name in props)) errors.push(`Missing required prop: "${rp.name}" (${rp.type})`);
|
|
200
|
+
}
|
|
201
|
+
const knownProps = new Set((detail.props || []).map(p => p.name));
|
|
202
|
+
for (const key of Object.keys(props)) {
|
|
203
|
+
if (!knownProps.has(key)) warnings.push(`Unknown prop: "${key}"`);
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
if (detail.accessibility?.ariaLabels?.length) {
|
|
208
|
+
bestPractices.push(`Accessibility: ${detail.accessibility.ariaLabels.join(', ')}`);
|
|
209
|
+
}
|
|
210
|
+
bestPractices.push('Use semantic design tokens instead of hardcoded values');
|
|
211
|
+
|
|
212
|
+
out({
|
|
213
|
+
component: component.name,
|
|
214
|
+
isValid: errors.length === 0,
|
|
215
|
+
errors,
|
|
216
|
+
warnings,
|
|
217
|
+
bestPractices,
|
|
218
|
+
requiredProps: (detail.props || []).filter(p => p.required).map(p => ({ name: p.name, type: p.type })),
|
|
219
|
+
});
|
|
220
|
+
},
|
|
221
|
+
|
|
222
|
+
guidelines() {
|
|
223
|
+
const variant = args[0] || 'common';
|
|
224
|
+
const file = variant === 'figma' ? 'prompts/figma-system-prompt.md' : 'prompts/common-system-prompt.md';
|
|
225
|
+
const promptPath = path.join(KB, file);
|
|
226
|
+
if (!fs.existsSync(promptPath)) {
|
|
227
|
+
console.error(JSON.stringify({ error: `Prompt file not found: ${file}` }));
|
|
228
|
+
process.exit(1);
|
|
229
|
+
}
|
|
230
|
+
console.log(fs.readFileSync(promptPath, 'utf8'));
|
|
231
|
+
},
|
|
232
|
+
|
|
233
|
+
stats() {
|
|
234
|
+
const summaries = readJson('components/metadata/summaries.json');
|
|
235
|
+
const tokens = readJson('design-tokens/tokens.json');
|
|
236
|
+
const icons = readJson('search-index/icons/collection.json');
|
|
237
|
+
|
|
238
|
+
const byCategory = summaries.reduce((acc, c) => { acc[c.category] = (acc[c.category] || 0) + 1; return acc; }, {});
|
|
239
|
+
const byStatus = summaries.reduce((acc, c) => { acc[c.status] = (acc[c.status] || 0) + 1; return acc; }, {});
|
|
240
|
+
|
|
241
|
+
out({
|
|
242
|
+
components: { total: summaries.length, byCategory, byStatus },
|
|
243
|
+
icons: {
|
|
244
|
+
total: (icons.system || []).length + (icons.assets || []).length,
|
|
245
|
+
system: (icons.system || []).length,
|
|
246
|
+
asset: (icons.assets || []).length,
|
|
247
|
+
},
|
|
248
|
+
tokens: {
|
|
249
|
+
colors: Object.keys({ ...tokens.colors?.primitive, ...tokens.colors?.semantic, ...tokens.colors?.alias }).length,
|
|
250
|
+
spacing: Object.keys(tokens.spacing || {}).length,
|
|
251
|
+
typography: Object.keys(tokens.typography?.fontSizes || {}).length,
|
|
252
|
+
},
|
|
253
|
+
});
|
|
254
|
+
},
|
|
255
|
+
};
|
|
256
|
+
|
|
257
|
+
if (!cmd || !commands[cmd]) {
|
|
258
|
+
console.error(`Usage: clad-ui-helper.js <command> [args]\nCommands: ${Object.keys(commands).join(', ')}`);
|
|
259
|
+
process.exit(1);
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
try {
|
|
263
|
+
commands[cmd]();
|
|
264
|
+
} catch (err) {
|
|
265
|
+
console.error(JSON.stringify({ error: err.message }));
|
|
266
|
+
process.exit(1);
|
|
267
|
+
}
|
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
# Clad UI Knowledge Base
|
|
2
|
+
|
|
3
|
+
This is the knowledge base extraction and processing system for the Clad UI Design System MCP Server.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
The knowledge base extracts comprehensive information from the Clad UI Design System and converts it into a structured format optimized for AI agent consumption.
|
|
8
|
+
|
|
9
|
+
## Structure
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
clad-ui-knowledge-base/
|
|
13
|
+
├── src/
|
|
14
|
+
│ ├── config/ # Configuration files
|
|
15
|
+
│ ├── extractors/ # Data extraction utilities
|
|
16
|
+
│ ├── processors/ # Data processing and building
|
|
17
|
+
│ ├── types/ # TypeScript type definitions
|
|
18
|
+
│ └── utils/ # Utility functions
|
|
19
|
+
├── components/ # Extracted component data
|
|
20
|
+
│ ├── metadata/ # Component metadata and info
|
|
21
|
+
│ ├── props/ # Component prop definitions
|
|
22
|
+
│ ├── examples/ # Usage examples
|
|
23
|
+
│ └── variants/ # Component variants
|
|
24
|
+
├── design-tokens/ # Design system tokens
|
|
25
|
+
├── patterns/ # Pattern and documentation data
|
|
26
|
+
├── search-index/ # Search indices
|
|
27
|
+
└── validation-rules/ # Usage validation rules
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Data Source
|
|
31
|
+
|
|
32
|
+
The knowledge base extracts data from **the same workspace**:
|
|
33
|
+
- `packages/clad-ui/` - Core components and patterns
|
|
34
|
+
- `packages/charts/` - Chart components
|
|
35
|
+
- `website/` - Documentation and guides
|
|
36
|
+
|
|
37
|
+
All paths are configured in `src/config/paths.ts` to read from the monorepo workspace.
|
|
38
|
+
|
|
39
|
+
## Usage
|
|
40
|
+
|
|
41
|
+
### From MCP Server Root (Recommended)
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
cd packages/mcp-server
|
|
45
|
+
pnpm build:knowledge-base
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
This runs the complete extraction and build process.
|
|
49
|
+
|
|
50
|
+
### From Knowledge Base Directory
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
cd packages/mcp-server/clad-ui-knowledge-base
|
|
54
|
+
|
|
55
|
+
# Extract all data
|
|
56
|
+
pnpm extract
|
|
57
|
+
|
|
58
|
+
# Build unified database
|
|
59
|
+
pnpm build
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
The extraction process:
|
|
63
|
+
1. Scans all story files matching Storybook configuration
|
|
64
|
+
2. Extracts component metadata from TypeScript files
|
|
65
|
+
3. Parses MDX documentation files
|
|
66
|
+
4. Indexes design tokens from theme files
|
|
67
|
+
5. Builds search indices
|
|
68
|
+
|
|
69
|
+
### Generate Statistics
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
node src/processors/build-database.js --stats
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Extracted Data
|
|
76
|
+
|
|
77
|
+
### Components
|
|
78
|
+
|
|
79
|
+
- **Metadata**: Name, category, status, description, Figma links
|
|
80
|
+
- **Props**: TypeScript interface definitions with types and descriptions
|
|
81
|
+
- **Variants**: Different component configurations from stories
|
|
82
|
+
- **Examples**: Usage examples and code snippets
|
|
83
|
+
- **Design Tokens**: Colors, spacing, typography tokens used
|
|
84
|
+
|
|
85
|
+
### Design Tokens
|
|
86
|
+
|
|
87
|
+
- **Colors**: Primitive, semantic, and alias color definitions
|
|
88
|
+
- **Typography**: Font families, sizes, weights, line heights, type scale
|
|
89
|
+
- **Spacing**: Margin and padding scale
|
|
90
|
+
- **Layout**: Breakpoints and grid system
|
|
91
|
+
- **Effects**: Border radius, shadows, z-indices
|
|
92
|
+
|
|
93
|
+
### Documentation
|
|
94
|
+
|
|
95
|
+
- **Style Guide**: Colors, typography, icons, layout documentation
|
|
96
|
+
- **About**: Introduction, getting started, theming guides
|
|
97
|
+
- **Patterns**: Composite component patterns and usage
|
|
98
|
+
|
|
99
|
+
## Output Files
|
|
100
|
+
|
|
101
|
+
- `clad-ui-database.json` - Unified knowledge base
|
|
102
|
+
- `component-categories.json` - Components organized by category
|
|
103
|
+
- `validation-rules/component-rules.json` - Component usage validation rules
|
|
104
|
+
- `stats.json` - Knowledge base statistics
|
|
105
|
+
|
|
106
|
+
## Integration with MCP Server
|
|
107
|
+
|
|
108
|
+
The extracted knowledge base is designed to be consumed by the MCP Server tools:
|
|
109
|
+
|
|
110
|
+
1. **list_components** - Uses component summaries
|
|
111
|
+
2. **get_component_info** - Uses detailed component information
|
|
112
|
+
3. **search_components** - Uses search indices
|
|
113
|
+
4. **get_design_tokens** - Uses design token definitions
|
|
114
|
+
5. **validate_usage** - Uses validation rules
|
|
115
|
+
|
|
116
|
+
## Development
|
|
117
|
+
|
|
118
|
+
The extraction system is built with TypeScript and uses:
|
|
119
|
+
|
|
120
|
+
- **@babel/parser** - For parsing TypeScript/JavaScript files
|
|
121
|
+
- **gray-matter** - For parsing MDX frontmatter
|
|
122
|
+
- **glob** - For file pattern matching
|
|
123
|
+
|
|
124
|
+
### Adding New Extractors
|
|
125
|
+
|
|
126
|
+
1. Create extractor class in `src/extractors/`
|
|
127
|
+
2. Add to the main extraction orchestrator
|
|
128
|
+
3. Update type definitions in `src/types/`
|
|
129
|
+
4. Add tests for the new functionality
|
|
130
|
+
|
|
131
|
+
### Customizing Extraction
|
|
132
|
+
|
|
133
|
+
Modify `src/config/paths.ts` to adjust file patterns and paths for your specific setup.
|
|
134
|
+
|
|
135
|
+
## Scripts
|
|
136
|
+
|
|
137
|
+
- `npm run extract` - Run full extraction process
|
|
138
|
+
- `npm run extract:components` - Extract only component data
|
|
139
|
+
- `npm run extract:tokens` - Extract only design tokens
|
|
140
|
+
- `npm run extract:mdx` - Extract only MDX documentation
|
|
141
|
+
- `npm run build` - Build unified database
|
|
142
|
+
- `npm run validate` - Validate extracted data
|
|
143
|
+
|
|
144
|
+
## Contributing
|
|
145
|
+
|
|
146
|
+
1. Follow existing code patterns
|
|
147
|
+
2. Add appropriate TypeScript types
|
|
148
|
+
3. Include error handling
|
|
149
|
+
4. Add logging for debugging
|
|
150
|
+
5. Update documentation
|
|
151
|
+
|
|
152
|
+
## License
|
|
153
|
+
|
|
154
|
+
This knowledge base extraction system is part of the Clad UI Design System project.
|