rafters 0.0.5 → 0.0.7

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 (3) hide show
  1. package/README.md +131 -0
  2. package/dist/index.js +3937 -3369
  3. package/package.json +2 -1
package/README.md ADDED
@@ -0,0 +1,131 @@
1
+ # rafters
2
+
3
+ Design Intelligence CLI. Scaffold tokens, add components, and serve an MCP server so AI agents build UIs with designer-level judgment instead of guessing.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npx rafters init
9
+ ```
10
+
11
+ Or install globally:
12
+
13
+ ```bash
14
+ pnpm add -g rafters
15
+ ```
16
+
17
+ ## Commands
18
+
19
+ ### `rafters init`
20
+
21
+ Initialize a project with design tokens. Detects your framework, scaffolds `.rafters/` with a complete token system, and generates output files.
22
+
23
+ ```bash
24
+ rafters init # Interactive setup
25
+ rafters init --rebuild # Regenerate output files from existing tokens
26
+ rafters init --reset # Re-run generators fresh, replacing persisted tokens
27
+ rafters init --agent # JSON output for CI/machine consumption
28
+ ```
29
+
30
+ **Supported frameworks:** Next.js, Vite, Remix, React Router, Astro
31
+
32
+ **Export formats** (configured during init):
33
+
34
+ | Format | File | Default | Description |
35
+ |--------|------|---------|-------------|
36
+ | Tailwind CSS | `rafters.css` | Yes | CSS custom properties with `@theme` |
37
+ | TypeScript | `rafters.ts` | Yes | Type-safe constants with JSDoc intelligence |
38
+ | DTCG JSON | `rafters.json` | No | W3C Design Tokens standard format |
39
+ | Standalone CSS | `rafters.standalone.css` | No | Pre-built, no Tailwind required |
40
+
41
+ Automatically detects and migrates existing shadcn/ui color values. Requires Tailwind v4.
42
+
43
+ ### `rafters add [components...]`
44
+
45
+ Add components from the Rafters registry to your project.
46
+
47
+ ```bash
48
+ rafters add button dialog # Add specific components
49
+ rafters add --list # List all available components
50
+ rafters add --overwrite # Replace existing files
51
+ ```
52
+
53
+ Components include embedded design intelligence: cognitive load ratings (1-7), accessibility requirements, do/never guidance, and trust-building patterns. Dependencies are resolved automatically.
54
+
55
+ ### `rafters studio`
56
+
57
+ Launch Studio for visual token editing.
58
+
59
+ ```bash
60
+ rafters studio
61
+ ```
62
+
63
+ Opens a Vite-powered UI where you design by doing: pick a primary color, explain why, watch the system paint your scale. Every decision is recorded with reasoning so AI agents read intent instead of guessing.
64
+
65
+ ### `rafters mcp`
66
+
67
+ Start the MCP server for AI agent access via stdio transport.
68
+
69
+ ```bash
70
+ rafters mcp
71
+ ```
72
+
73
+ ## MCP Tools
74
+
75
+ Four tools give AI agents complete design system access:
76
+
77
+ ### `rafters_vocabulary`
78
+
79
+ System overview. Colors, spacing, typography, components, cognitive loads, and available patterns. Call this first to orient.
80
+
81
+ ### `rafters_pattern`
82
+
83
+ Deep guidance for specific UI scenarios. Returns which components to use, which tokens to apply, accessibility requirements, and do/never rules.
84
+
85
+ **Available patterns:** `destructive-action`, `form-validation`, `empty-state`, `loading-state`, `navigation-hierarchy`, `data-table`, `modal-dialog`, `tooltip-guidance`, `card-layout`, `dropdown-actions`
86
+
87
+ ### `rafters_component`
88
+
89
+ Full intelligence for a specific component. Cognitive load rating, attention economics, accessibility requirements, trust-building patterns, variants, sizes, and primitives.
90
+
91
+ ### `rafters_token`
92
+
93
+ Token dependency graph, derivation rules, and human override context. Returns how a token is computed, what it depends on, and whether a designer manually overrode it (with their reasoning).
94
+
95
+ **Derivation rules:** `calc()`, `state:hover`, `scale:600`, `contrast:auto`, `invert`
96
+
97
+ ## How It Works
98
+
99
+ Rafters is a Design Intelligence Protocol. AI agents don't have taste - they guess at colors, spacing, hierarchy. Rafters encodes a designer's judgment into queryable data so AI reads decisions instead of guessing.
100
+
101
+ Three layers:
102
+
103
+ - **What** (Components) - 55 React components with embedded intelligence metadata
104
+ - **Where** (Tokens) - 240+ tokens with dependency graph and human override tracking
105
+ - **Why** (Decisions) - Do/never patterns, cognitive load scores, trust patterns, accessibility requirements
106
+
107
+ The token system uses OKLCH color space, modular scales based on musical ratios, and a dependency engine that automatically derives related values. When a designer overrides a computed value, the system records the reason so AI agents respect the intent.
108
+
109
+ ## Project Structure
110
+
111
+ ```
112
+ .rafters/
113
+ config.rafters.json # Framework paths and export settings
114
+ tokens/
115
+ color.rafters.json # Color tokens with OKLCH values
116
+ spacing.rafters.json # Spacing scale
117
+ typography.rafters.json # Type scale
118
+ output/
119
+ rafters.css # Tailwind CSS export
120
+ rafters.ts # TypeScript constants
121
+ ```
122
+
123
+ ## Requirements
124
+
125
+ - Node.js >= 24.12.0
126
+ - Tailwind CSS v4
127
+ - React >= 19.0.0
128
+
129
+ ## License
130
+
131
+ MIT