@astralkit/mcp 1.9.1 → 1.10.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.
- package/CHANGELOG.md +7 -0
- package/dist/data/crosswalk.d.ts +1 -1
- package/dist/data/crosswalk.d.ts.map +1 -1
- package/dist/data/crosswalk.js +17 -15
- package/dist/data/crosswalk.js.map +1 -1
- package/dist/data/polish.js +16 -16
- package/dist/data/polish.js.map +1 -1
- package/dist/data/rules.d.ts +1 -1
- package/dist/data/rules.d.ts.map +1 -1
- package/dist/data/rules.js +183 -183
- package/dist/data/tokens.d.ts +1 -1
- package/dist/data/tokens.d.ts.map +1 -1
- package/dist/data/tokens.js +10 -31
- package/dist/data/tokens.js.map +1 -1
- package/dist/server.js +4 -4
- package/dist/server.js.map +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,13 @@ All notable changes to the `@astralkit/mcp` package.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [1.10.0] — 2026-08-23
|
|
9
|
+
|
|
10
|
+
### Changed (pairs with astralkit SDK 0.8.0 — spacing grammar renumbered)
|
|
11
|
+
- **Crosswalk is now identity for spacing**: `p-6` → `p-ak-6` (the ak scale uses core 4px-grid numbering). 6px/10px stay core `p-1.5`/`p-2.5`.
|
|
12
|
+
- Design-token docs teach the new one-rule grammar ("same number, add ak-"); pre-0.8 fraction names documented as deprecated.
|
|
13
|
+
- `dot-notation-spacing` rule updated for the new grammar.
|
|
14
|
+
|
|
8
15
|
## [1.9.1] — 2026-08-23
|
|
9
16
|
|
|
10
17
|
### Added
|
package/dist/data/crosswalk.d.ts
CHANGED
|
@@ -3,5 +3,5 @@
|
|
|
3
3
|
* Returns the replacement string, or null if there's no confident mapping.
|
|
4
4
|
*/
|
|
5
5
|
export declare function nearestToken(cls: string): string | null;
|
|
6
|
-
export declare const CROSSWALK = "# Raw Tailwind \u2192 AstralKit Crosswalk (for tokenizing existing UI)\n\n**Tokenization = replacing Tailwind utility CLASSES on the JSX elements, NOT writing CSS.**\n\nWhen converting a non-AstralKit screen, replace raw Tailwind classes with the nearest `ak-*`\nutility class directly on the `className` attribute. (`validate_code` also returns the exact\nsuggestion per flagged class \u2014 run it and apply each.)\n\n## \uD83D\uDD34 What tokenization is NOT (the #1 mistake)\nTokenization is NOT writing CSS custom properties (`var(--color-ak-*)`, `var(--spacing-ak-*)`)\ninto a stylesheet. That creates a parallel styling system instead of using the library.\n\n```tsx\n// \u2705 CORRECT \u2014 utility class on the element\n<div className=\"bg-ak-surface p-ak-
|
|
6
|
+
export declare const CROSSWALK = "# Raw Tailwind \u2192 AstralKit Crosswalk (for tokenizing existing UI)\n\n**Tokenization = replacing Tailwind utility CLASSES on the JSX elements, NOT writing CSS.**\n\nWhen converting a non-AstralKit screen, replace raw Tailwind classes with the nearest `ak-*`\nutility class directly on the `className` attribute. (`validate_code` also returns the exact\nsuggestion per flagged class \u2014 run it and apply each.)\n\n## \uD83D\uDD34 What tokenization is NOT (the #1 mistake)\nTokenization is NOT writing CSS custom properties (`var(--color-ak-*)`, `var(--spacing-ak-*)`)\ninto a stylesheet. That creates a parallel styling system instead of using the library.\n\n```tsx\n// \u2705 CORRECT \u2014 utility class on the element\n<div className=\"bg-ak-surface p-ak-6 rounded-ak-lg border border-ak-border\">\n\n// \u274C WRONG \u2014 CSS custom property in a stylesheet (globals.css, page.css, etc.)\n// .my-card { background: var(--color-ak-surface); padding: var(--spacing-ak-6); }\n// This is NOT tokenization. This is writing raw CSS that happens to reference ak variables.\n```\n\n**Rules:**\n- NEVER create CSS/stylesheet files (.css) for tokenization \u2014 all styling belongs as\n Tailwind utility classes on the JSX `className`.\n- NEVER use `var(--color-ak-*)`, `var(--spacing-ak-*)`, `var(--radius-ak-*)`, etc. in\n stylesheets \u2014 use the Tailwind class (`bg-ak-surface`, `p-ak-6`, `rounded-ak-lg`).\n- NEVER add `!important` \u2014 if specificity is fighting you, you're in the wrong layer.\n- **When the source already has external stylesheets** (page.css, styles.css, component.css,\n or custom rules in globals.css): READ the stylesheet, EXTRACT each CSS property,\n FIND the equivalent `ak-*` utility class using this crosswalk, APPLY those classes\n to the JSX elements, then DELETE the stylesheet and remove its import. The goal is\n zero custom CSS for visual styling \u2014 all of it lives on `className`.\n- **globals.css should be minimal** \u2014 only AstralKit theme/utilities imports and, at most,\n a few lines of CSS variable overrides (`--color-ak-primary: ...`) to customize the\n palette. Component styling does NOT belong there.\n\n### CSS property \u2192 ak-* class quick-reference (for extracting from stylesheets)\n```\nbackground: var(--color-ak-surface) \u2192 bg-ak-surface\ncolor: var(--color-ak-text) \u2192 text-ak-text\nborder-color: var(--color-ak-border) \u2192 border-ak-border\npadding: var(--spacing-ak-6) \u2192 p-ak-6\ngap: var(--spacing-ak-4) \u2192 gap-ak-4\nborder-radius: var(--radius-ak-lg) \u2192 rounded-ak-lg\nfont-size: var(--text-ak-base) \u2192 text-ak-base\nfont-size: 16px / 1rem \u2192 text-ak-base\nfont-size: 14px / 0.875rem \u2192 text-ak-sm\nmin-height: 3rem / 48px \u2192 min-h-ak-control-lg\nwidth: 3rem / height: 3rem \u2192 size-ak-avatar-lg\n```\n\n## What properly tokenized code looks like\nAstralKit's own library components are the gold standard. In a properly tokenized file:\n- Every element's `className` uses `ak-*` tokens for ALL spacing, colors, radii, typography\n- There is NO external stylesheet \u2014 zero `.css` files for component styling\n- There are NO CSS custom property references (`var(--color-ak-*)`) outside `globals.css`\n- `globals.css` contains ONLY the theme/utilities imports and optional palette overrides\n- All visual nuance lives on the markup via utility classes \u2014 the code reads as a recipe\n\nExample of a properly tokenized stat card:\n```tsx\n<div className=\"rounded-ak-xl border border-ak-border bg-ak-elevated p-ak-6\">\n <p className=\"text-ak-xs font-medium uppercase tracking-ak-wide text-ak-text-secondary\">\n Total Revenue\n </p>\n <p className=\"mt-ak-2 text-ak-3xl font-bold text-ak-text tabular-nums\">$45,231</p>\n <span className=\"mt-ak-1 inline-flex rounded-ak-full bg-ak-success-subtle px-ak-2 py-ak-1 text-ak-xs font-semibold text-ak-success-text\">\n +20.1%\n </span>\n</div>\n```\n\nThis is the taste level: proper hierarchy (3xl value, xs label), the ak-* rhythm, semantic\nsurfaces and status colors, no raw Tailwind, no CSS file, no inline styles.\n\n### Example: extracting from an existing stylesheet\nIf the source has `import './card.css'` and `card.css` contains:\n```css\n.stat-card { background: #fff; border: 1px solid #e5e5e5; border-radius: 0.75rem; padding: 1rem; }\n.stat-label { font-size: 0.75rem; color: #737373; text-transform: uppercase; letter-spacing: 0.05em; }\n.stat-value { font-size: 1.5rem; font-weight: 700; color: #171717; }\n```\nThe correct tokenization is:\n1. Map each property \u2192 `bg-ak-elevated`, `border border-ak-border`, `rounded-ak-lg`, `p-ak-4`,\n `text-ak-xs text-ak-text-secondary uppercase tracking-ak-wide`, `text-ak-2xl font-bold text-ak-text`\n2. Apply those classes to the JSX elements that used `.stat-card`, `.stat-label`, `.stat-value`\n3. DELETE `card.css` and remove the `import './card.css'` line\n4. The result is zero CSS, all styling on `className`\n\n## Colors\n| Raw Tailwind | AstralKit |\n|---|---|\n| `bg-white`, `bg-gray-50` | `bg-ak-bg` |\n| `bg-black` | `bg-ak-inverse-surface` |\n| `text-white` | `text-ak-text-inverse` |\n| `text-black` | `text-ak-text` |\n| `bg-gray-100` / `bg-gray-200` | `bg-ak-surface` / `bg-ak-surface-2` |\n| `bg-gray-800`/`-900`/`-950` (dark buttons) | `bg-ak-primary` (+ `hover:bg-ak-primary-hover`, `text-ak-on-primary`) |\n| `text-gray-900` / `-600,-500` / `-400` | `text-ak-text` / `text-ak-text-secondary` / `text-ak-text-muted` |\n| `border-gray-200`, `divide-gray-100` | `border-ak-border`, `divide-ak-border-subtle` |\n| green/emerald/teal `-500` / `-50` / `-700` | `ak-success` / `ak-success-subtle` / `ak-success-text` |\n| red/rose | `ak-danger` (+ `-subtle`/`-text`) |\n| amber/yellow/orange | `ak-warning` (+ `-subtle`/`-text`) |\n| blue/sky/cyan | `ak-info` (+ `-subtle`/`-text`) |\n| indigo/violet/purple (brand accent) | `ak-primary` (AstralKit's accent is monochrome by default \u2014 drop random purples/gradients) |\n\n## Spacing (Tailwind n \u2192 ak)\n`-2`\u2192`ak-1` \u00B7 `-3`\u2192`ak-1_5` \u00B7 `-4`\u2192`ak-2` \u00B7 `-5`\u2192`ak-2_5` \u00B7 `-6`\u2192`ak-3` \u00B7 `-8`\u2192`ak-4` \u00B7 `-10`\u2192`ak-5` \u00B7 `-12`\u2192`ak-6` \u00B7 `-16`\u2192`ak-8`\n(applies to `p* m* gap space-*`; e.g. `p-6`\u2192`p-ak-6`, `gap-4`\u2192`gap-ak-4`)\n\n## Radius / type\n`rounded-lg`\u2192`rounded-ak-lg`, `rounded-xl`\u2192`rounded-ak-xl`, `rounded-full`\u2192`rounded-ak-full` \u00B7 `text-sm`\u2192`text-ak-sm`, `text-2xl`\u2192`text-ak-2xl` (body stays `text-ak-base` min).\n\n## Also when tokenizing\n- ALL styling goes on `className` \u2014 never write component styling to globals.css, page.css,\n or any stylesheet. If the source has external stylesheets with visual rules, EXTRACT the\n properties, CONVERT each to the nearest `ak-*` utility class, APPLY them to the JSX\n elements, DELETE the stylesheet file, and remove the import. globals.css keeps only the\n theme/utilities imports + optional palette overrides.\n- Swap any icon library / inline `<svg>` UI icons \u2192 `@phosphor-icons/react` (confirm names via get_icons). Brand logos \u2192 search_logos.\n- Raise sub-16px body text to `text-ak-base`; add `focus-visible` rings and 48px touch targets.\n- Rebuild charts with the chart recipe (definite height + `ak-chart-*`). Add empty/loading/error states.\n\n## Dark mode\nAstralKit themes are structural \u2014 set `data-ak-theme=\"dark\"` on the root (or a section)\nand the SAME semantic tokens flip to dark values automatically. You do NOT need a separate\ndark-mode crosswalk:\n| Token | Light | Dark |\n|---|---|---|\n| `bg-ak-bg` | near-white | near-black |\n| `bg-ak-surface` | light gray | dark gray |\n| `text-ak-text` | near-black | near-white |\n| `border-ak-border` | light gray | dark gray |\nThe mapping is the same: `bg-gray-50` \u2192 `bg-ak-bg` whether the source is a light or dark\napp. The theme attribute does the flipping. **PRESERVE the source theme** \u2014 if the app is dark,\nset `data-ak-theme=\"dark\"` and use the same semantic tokens (they auto-adapt). Never map a\ndark source to light tokens; that breaks the design.\n\n## CSS Modules (`*.module.css`)\nTreat CSS modules exactly like any other stylesheet: READ the file, EXTRACT each CSS property,\nFIND the equivalent `ak-*` utility class, APPLY the classes to the JSX elements, DELETE the\n`.module.css` file, and remove the import + all `styles.*` references. Replace\n`className={styles.card}` with `className=\"bg-ak-elevated rounded-ak-xl ...\"`.\n\n## `@apply` directives\nIf the source uses `@apply` in CSS (e.g. `@apply p-4 bg-white rounded-lg`), extract the\nutilities listed, convert each to its `ak-*` equivalent, apply them to the JSX `className`,\nand delete the CSS rule. NEVER convert `@apply p-4` to `@apply p-ak-4` \u2014 the goal is zero\nCSS for component styling. All styling belongs on the element's `className`.\n";
|
|
7
7
|
//# sourceMappingURL=crosswalk.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"crosswalk.d.ts","sourceRoot":"","sources":["../../src/data/crosswalk.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"crosswalk.d.ts","sourceRoot":"","sources":["../../src/data/crosswalk.ts"],"names":[],"mappings":"AA4CA;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAuCvD;AAED,eAAO,MAAM,SAAS,q1RAqJrB,CAAC"}
|
package/dist/data/crosswalk.js
CHANGED
|
@@ -22,11 +22,13 @@ const BARE_COLORS = {
|
|
|
22
22
|
'ring-black': 'ring-ak-text',
|
|
23
23
|
};
|
|
24
24
|
// Tailwind spacing step (n × 0.25rem) → ak spacing token (matched by rem).
|
|
25
|
+
// Since SDK 0.8.0 the ak scale uses core numbering (ak-N = N x 4px, fluid) —
|
|
26
|
+
// the crosswalk is IDENTITY for on-grid steps. 1.5/2.5 (6px/10px) stay core.
|
|
25
27
|
const SPACING = {
|
|
26
|
-
'0': 'ak-0', '0.5': 'ak-
|
|
27
|
-
'
|
|
28
|
-
'6': 'ak-
|
|
29
|
-
'11': 'ak-
|
|
28
|
+
'0': 'ak-0', '0.5': 'ak-1', '1': 'ak-1', '2': 'ak-2',
|
|
29
|
+
'3': 'ak-3', '3.5': 'ak-3', '4': 'ak-4', '5': 'ak-5',
|
|
30
|
+
'6': 'ak-6', '7': 'ak-7', '8': 'ak-8', '9': 'ak-9', '10': 'ak-10',
|
|
31
|
+
'11': 'ak-11', '12': 'ak-12', '14': 'ak-14', '16': 'ak-16', '20': 'ak-20', '24': 'ak-24',
|
|
30
32
|
};
|
|
31
33
|
const RADIUS = {
|
|
32
34
|
none: 'rounded-ak-none', sm: 'rounded-ak-sm', '': 'rounded-ak-md', md: 'rounded-ak-md',
|
|
@@ -106,10 +108,10 @@ into a stylesheet. That creates a parallel styling system instead of using the l
|
|
|
106
108
|
|
|
107
109
|
\`\`\`tsx
|
|
108
110
|
// ✅ CORRECT — utility class on the element
|
|
109
|
-
<div className="bg-ak-surface p-ak-
|
|
111
|
+
<div className="bg-ak-surface p-ak-6 rounded-ak-lg border border-ak-border">
|
|
110
112
|
|
|
111
113
|
// ❌ WRONG — CSS custom property in a stylesheet (globals.css, page.css, etc.)
|
|
112
|
-
// .my-card { background: var(--color-ak-surface); padding: var(--spacing-ak-
|
|
114
|
+
// .my-card { background: var(--color-ak-surface); padding: var(--spacing-ak-6); }
|
|
113
115
|
// This is NOT tokenization. This is writing raw CSS that happens to reference ak variables.
|
|
114
116
|
\`\`\`
|
|
115
117
|
|
|
@@ -117,7 +119,7 @@ into a stylesheet. That creates a parallel styling system instead of using the l
|
|
|
117
119
|
- NEVER create CSS/stylesheet files (.css) for tokenization — all styling belongs as
|
|
118
120
|
Tailwind utility classes on the JSX \`className\`.
|
|
119
121
|
- NEVER use \`var(--color-ak-*)\`, \`var(--spacing-ak-*)\`, \`var(--radius-ak-*)\`, etc. in
|
|
120
|
-
stylesheets — use the Tailwind class (\`bg-ak-surface\`, \`p-ak-
|
|
122
|
+
stylesheets — use the Tailwind class (\`bg-ak-surface\`, \`p-ak-6\`, \`rounded-ak-lg\`).
|
|
121
123
|
- NEVER add \`!important\` — if specificity is fighting you, you're in the wrong layer.
|
|
122
124
|
- **When the source already has external stylesheets** (page.css, styles.css, component.css,
|
|
123
125
|
or custom rules in globals.css): READ the stylesheet, EXTRACT each CSS property,
|
|
@@ -133,8 +135,8 @@ into a stylesheet. That creates a parallel styling system instead of using the l
|
|
|
133
135
|
background: var(--color-ak-surface) → bg-ak-surface
|
|
134
136
|
color: var(--color-ak-text) → text-ak-text
|
|
135
137
|
border-color: var(--color-ak-border) → border-ak-border
|
|
136
|
-
padding: var(--spacing-ak-
|
|
137
|
-
gap: var(--spacing-ak-
|
|
138
|
+
padding: var(--spacing-ak-6) → p-ak-6
|
|
139
|
+
gap: var(--spacing-ak-4) → gap-ak-4
|
|
138
140
|
border-radius: var(--radius-ak-lg) → rounded-ak-lg
|
|
139
141
|
font-size: var(--text-ak-base) → text-ak-base
|
|
140
142
|
font-size: 16px / 1rem → text-ak-base
|
|
@@ -153,12 +155,12 @@ AstralKit's own library components are the gold standard. In a properly tokenize
|
|
|
153
155
|
|
|
154
156
|
Example of a properly tokenized stat card:
|
|
155
157
|
\`\`\`tsx
|
|
156
|
-
<div className="rounded-ak-xl border border-ak-border bg-ak-elevated p-ak-
|
|
158
|
+
<div className="rounded-ak-xl border border-ak-border bg-ak-elevated p-ak-6">
|
|
157
159
|
<p className="text-ak-xs font-medium uppercase tracking-ak-wide text-ak-text-secondary">
|
|
158
160
|
Total Revenue
|
|
159
161
|
</p>
|
|
160
|
-
<p className="mt-ak-
|
|
161
|
-
<span className="mt-ak-
|
|
162
|
+
<p className="mt-ak-2 text-ak-3xl font-bold text-ak-text tabular-nums">$45,231</p>
|
|
163
|
+
<span className="mt-ak-1 inline-flex rounded-ak-full bg-ak-success-subtle px-ak-2 py-ak-1 text-ak-xs font-semibold text-ak-success-text">
|
|
162
164
|
+20.1%
|
|
163
165
|
</span>
|
|
164
166
|
</div>
|
|
@@ -175,7 +177,7 @@ If the source has \`import './card.css'\` and \`card.css\` contains:
|
|
|
175
177
|
.stat-value { font-size: 1.5rem; font-weight: 700; color: #171717; }
|
|
176
178
|
\`\`\`
|
|
177
179
|
The correct tokenization is:
|
|
178
|
-
1. Map each property → \`bg-ak-elevated\`, \`border border-ak-border\`, \`rounded-ak-lg\`, \`p-ak-
|
|
180
|
+
1. Map each property → \`bg-ak-elevated\`, \`border border-ak-border\`, \`rounded-ak-lg\`, \`p-ak-4\`,
|
|
179
181
|
\`text-ak-xs text-ak-text-secondary uppercase tracking-ak-wide\`, \`text-ak-2xl font-bold text-ak-text\`
|
|
180
182
|
2. Apply those classes to the JSX elements that used \`.stat-card\`, \`.stat-label\`, \`.stat-value\`
|
|
181
183
|
3. DELETE \`card.css\` and remove the \`import './card.css'\` line
|
|
@@ -200,7 +202,7 @@ The correct tokenization is:
|
|
|
200
202
|
|
|
201
203
|
## Spacing (Tailwind n → ak)
|
|
202
204
|
\`-2\`→\`ak-1\` · \`-3\`→\`ak-1_5\` · \`-4\`→\`ak-2\` · \`-5\`→\`ak-2_5\` · \`-6\`→\`ak-3\` · \`-8\`→\`ak-4\` · \`-10\`→\`ak-5\` · \`-12\`→\`ak-6\` · \`-16\`→\`ak-8\`
|
|
203
|
-
(applies to \`p* m* gap space-*\`; e.g. \`p-6\`→\`p-ak-
|
|
205
|
+
(applies to \`p* m* gap space-*\`; e.g. \`p-6\`→\`p-ak-6\`, \`gap-4\`→\`gap-ak-4\`)
|
|
204
206
|
|
|
205
207
|
## Radius / type
|
|
206
208
|
\`rounded-lg\`→\`rounded-ak-lg\`, \`rounded-xl\`→\`rounded-ak-xl\`, \`rounded-full\`→\`rounded-ak-full\` · \`text-sm\`→\`text-ak-sm\`, \`text-2xl\`→\`text-ak-2xl\` (body stays \`text-ak-base\` min).
|
|
@@ -239,7 +241,7 @@ FIND the equivalent \`ak-*\` utility class, APPLY the classes to the JSX element
|
|
|
239
241
|
## \`@apply\` directives
|
|
240
242
|
If the source uses \`@apply\` in CSS (e.g. \`@apply p-4 bg-white rounded-lg\`), extract the
|
|
241
243
|
utilities listed, convert each to its \`ak-*\` equivalent, apply them to the JSX \`className\`,
|
|
242
|
-
and delete the CSS rule. NEVER convert \`@apply p-4\` to \`@apply p-ak-
|
|
244
|
+
and delete the CSS rule. NEVER convert \`@apply p-4\` to \`@apply p-ak-4\` — the goal is zero
|
|
243
245
|
CSS for component styling. All styling belongs on the element's \`className\`.
|
|
244
246
|
`;
|
|
245
247
|
//# sourceMappingURL=crosswalk.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"crosswalk.js","sourceRoot":"","sources":["../../src/data/crosswalk.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,gFAAgF;AAChF,2FAA2F;AAE3F,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AACpE,mDAAmD;AACnD,MAAM,QAAQ,GAA6B;IACzC,OAAO,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC;IAC7C,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC;IACtC,IAAI,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC;IAC7B,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,gCAAgC;IACpF,IAAI,EAAE,CAAC,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,WAAW,GAA2B;IAC1C,UAAU,EAAE,UAAU;IACtB,UAAU,EAAE,uBAAuB;IACnC,YAAY,EAAE,sBAAsB;IACpC,YAAY,EAAE,cAAc;IAC5B,cAAc,EAAE,cAAc;IAC9B,cAAc,EAAE,gBAAgB;IAChC,YAAY,EAAE,YAAY;IAC1B,YAAY,EAAE,cAAc;CAC7B,CAAC;AAEF,2EAA2E;AAC3E,MAAM,OAAO,GAA2B;IACtC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,
|
|
1
|
+
{"version":3,"file":"crosswalk.js","sourceRoot":"","sources":["../../src/data/crosswalk.ts"],"names":[],"mappings":"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"}
|
package/dist/data/polish.js
CHANGED
|
@@ -13,7 +13,7 @@ export const ARCHETYPE_MAP = {
|
|
|
13
13
|
category: 'Forms', query: 'contact form', flagship: true,
|
|
14
14
|
rules: [
|
|
15
15
|
'label/field weight pair: label font-medium text-ak-sm, input text-ak-base',
|
|
16
|
-
'field height min-h-ak-control-lg (48px), generous gap-ak-
|
|
16
|
+
'field height min-h-ak-control-lg (48px), generous gap-ak-6 between rows',
|
|
17
17
|
'helper/error text text-ak-sm text-ak-text-secondary / text-ak-danger-text',
|
|
18
18
|
'group related fields; section the form with clear vertical rhythm',
|
|
19
19
|
'focus-visible rings on every control; border-ak-border not shadow',
|
|
@@ -22,7 +22,7 @@ export const ARCHETYPE_MAP = {
|
|
|
22
22
|
'form-field': {
|
|
23
23
|
category: 'Forms', query: 'input field',
|
|
24
24
|
rules: [
|
|
25
|
-
'min-h-ak-control-lg, px-ak-
|
|
25
|
+
'min-h-ak-control-lg, px-ak-4 py-ak-2, rounded-ak-lg, border-ak-border',
|
|
26
26
|
'label above (font-medium text-ak-sm), helper below (text-ak-sm text-ak-text-secondary)',
|
|
27
27
|
'focus-visible:ring-2 ring-ak-border-focus',
|
|
28
28
|
],
|
|
@@ -41,7 +41,7 @@ export const ARCHETYPE_MAP = {
|
|
|
41
41
|
category: 'Navigation', query: 'sidebar navigation', flagship: true,
|
|
42
42
|
rules: [
|
|
43
43
|
'active item: bg-ak-active text-ak-text; inactive: text-ak-text-secondary hover:bg-ak-hover',
|
|
44
|
-
'icon+label rows with consistent gap-ak-
|
|
44
|
+
'icon+label rows with consistent gap-ak-4 and min-h-ak-control-md tap targets',
|
|
45
45
|
'section labels uppercase text-ak-xs tracked text-ak-text-muted',
|
|
46
46
|
'border-ak-border divider, flat surface (bg-ak-surface), no shadow',
|
|
47
47
|
],
|
|
@@ -49,7 +49,7 @@ export const ARCHETYPE_MAP = {
|
|
|
49
49
|
'sidebar-nav': {
|
|
50
50
|
category: 'Navigation', query: 'nav menu item',
|
|
51
51
|
rules: [
|
|
52
|
-
'row: gap-ak-
|
|
52
|
+
'row: gap-ak-4, px-ak-4 py-ak-2, rounded-ak-lg',
|
|
53
53
|
'active bg-ak-active; hover bg-ak-hover; focus-visible ring',
|
|
54
54
|
'Phosphor icon size 20, label text-ak-base font-medium',
|
|
55
55
|
],
|
|
@@ -57,31 +57,31 @@ export const ARCHETYPE_MAP = {
|
|
|
57
57
|
card: {
|
|
58
58
|
category: 'Cards', query: 'card',
|
|
59
59
|
rules: [
|
|
60
|
-
'card chrome p-ak-
|
|
60
|
+
'card chrome p-ak-8, rounded-ak-2xl, border-ak-border, bg-ak-elevated, NO shadow',
|
|
61
61
|
'title text-ak-lg font-semibold; body text-ak-base text-ak-text-secondary',
|
|
62
|
-
'internal gap-ak-
|
|
62
|
+
'internal gap-ak-6; separate title row from meta row',
|
|
63
63
|
],
|
|
64
64
|
},
|
|
65
65
|
'kanban-card': {
|
|
66
66
|
category: 'Cards', query: 'task card',
|
|
67
67
|
rules: [
|
|
68
|
-
'card chrome p-ak-
|
|
68
|
+
'card chrome p-ak-8, rounded-ak-xl, border-ak-border, bg-ak-elevated, NO shadow',
|
|
69
69
|
'title/meta weight pair: title text-ak-base font-semibold, meta text-ak-sm text-ak-text-secondary',
|
|
70
70
|
'status as a pill badge (bg-ak-*-subtle text-ak-*-text), not raw colored text',
|
|
71
|
-
'eyebrow/label uppercase text-ak-xs tracked; consistent gap-ak-
|
|
71
|
+
'eyebrow/label uppercase text-ak-xs tracked; consistent gap-ak-4',
|
|
72
72
|
],
|
|
73
73
|
},
|
|
74
74
|
'stat-tile': {
|
|
75
75
|
category: 'Cards', query: 'stat metric kpi',
|
|
76
76
|
rules: [
|
|
77
77
|
'extreme size jump: value text-ak-3xl+ font-bold, label text-ak-sm text-ak-text-secondary',
|
|
78
|
-
'card chrome p-ak-
|
|
78
|
+
'card chrome p-ak-8 border-ak-border; delta as small colored pill',
|
|
79
79
|
],
|
|
80
80
|
},
|
|
81
81
|
'list-row': {
|
|
82
82
|
category: 'Lists', query: 'list row item',
|
|
83
83
|
rules: [
|
|
84
|
-
'py-ak-
|
|
84
|
+
'py-ak-4, divide-ak-border between rows, hover:bg-ak-hover',
|
|
85
85
|
'primary text-ak-base font-medium, secondary text-ak-sm text-ak-text-secondary',
|
|
86
86
|
],
|
|
87
87
|
},
|
|
@@ -89,7 +89,7 @@ export const ARCHETYPE_MAP = {
|
|
|
89
89
|
category: 'Tables', query: 'data table',
|
|
90
90
|
rules: [
|
|
91
91
|
'header uppercase text-ak-xs tracked text-ak-text-muted; cells text-ak-base',
|
|
92
|
-
'row divide-ak-border, hover:bg-ak-hover, py-ak-
|
|
92
|
+
'row divide-ak-border, hover:bg-ak-hover, py-ak-4 px-ak-4',
|
|
93
93
|
'numeric columns tabular-nums right-aligned',
|
|
94
94
|
],
|
|
95
95
|
},
|
|
@@ -103,22 +103,22 @@ export const ARCHETYPE_MAP = {
|
|
|
103
103
|
badge: {
|
|
104
104
|
category: 'Badges', query: 'badge pill status',
|
|
105
105
|
rules: [
|
|
106
|
-
'rounded-ak-full, px-ak-
|
|
106
|
+
'rounded-ak-full, px-ak-2 py-ak-1, text-ak-xs font-semibold',
|
|
107
107
|
'semantic tone subtle+text pair (bg-ak-success-subtle text-ak-success-text)',
|
|
108
108
|
],
|
|
109
109
|
},
|
|
110
110
|
button: {
|
|
111
111
|
category: 'Forms', query: 'button variants',
|
|
112
112
|
rules: [
|
|
113
|
-
'min-h-ak-control-lg, px-ak-
|
|
113
|
+
'min-h-ak-control-lg, px-ak-5, rounded-ak-xl, font-semibold text-ak-base',
|
|
114
114
|
'primary bg-ak-primary text-ak-on-primary hover:bg-ak-primary-hover',
|
|
115
|
-
'focus-visible:ring-2; gap-ak-
|
|
115
|
+
'focus-visible:ring-2; gap-ak-2 to icon',
|
|
116
116
|
],
|
|
117
117
|
},
|
|
118
118
|
modal: {
|
|
119
119
|
category: 'Overlays', query: 'modal dialog',
|
|
120
120
|
rules: [
|
|
121
|
-
'rounded-ak-2xl, p-ak-
|
|
121
|
+
'rounded-ak-2xl, p-ak-8, bg-ak-elevated; shadow IS allowed (floating element)',
|
|
122
122
|
'title text-ak-lg font-semibold; actions row with primary/secondary buttons',
|
|
123
123
|
],
|
|
124
124
|
},
|
|
@@ -203,7 +203,7 @@ const SMELL_RUBRIC = `## Design-Smell Rubric (diagnose, then fix to target)
|
|
|
203
203
|
|---|---|
|
|
204
204
|
| Weak hierarchy — title barely bigger than body | 3x+ size jumps; use heading presets (ak-card-title, display sizes). Body stays text-ak-base |
|
|
205
205
|
| Flat weight — everything one font-weight | Weight pairs: font-semibold titles / font-medium labels / normal body / uppercase-tracked text-ak-xs eyebrows |
|
|
206
|
-
| Off-scale / cramped spacing | Snap to the ak-* rhythm; card chrome p-ak-
|
|
206
|
+
| Off-scale / cramped spacing | Snap to the ak-* rhythm; card chrome p-ak-8, internal gap-ak-6, section rhythm via fluid tokens |
|
|
207
207
|
| Wrong surface treatment — shadows on cards, gradients everywhere | border border-ak-border, NO shadow on containment surfaces; gradients hero/marketing only |
|
|
208
208
|
| Missing structure — no eyebrow, title+meta crammed | Add an eyebrow/label, split title and meta into separate rows (additive) |
|
|
209
209
|
| 60-30-10 broken — accent overused | Accent ≤10%; neutrals dominate the canvas |
|
package/dist/data/polish.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"polish.js","sourceRoot":"","sources":["../../src/data/polish.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,wFAAwF;AACxF,EAAE;AACF,6EAA6E;AAC7E,kFAAkF;AAClF,+EAA+E;AAC/E,0CAA0C;AAa1C,oFAAoF;AACpF,iFAAiF;AACjF,oEAAoE;AACpE,MAAM,CAAC,MAAM,aAAa,GAAmC;IAC3D,IAAI,EAAE;QACJ,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,IAAI;QACxD,KAAK,EAAE;YACL,2EAA2E;YAC3E,yEAAyE;YACzE,2EAA2E;YAC3E,mEAAmE;YACnE,mEAAmE;SACpE;KACF;IACD,YAAY,EAAE;QACZ,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa;QACvC,KAAK,EAAE;YACL,uEAAuE;YACvE,wFAAwF;YACxF,2CAA2C;SAC5C;KACF;IACD,MAAM,EAAE;QACN,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI;QACpD,KAAK,EAAE;YACL,2EAA2E;YAC3E,oFAAoF;YACpF,sFAAsF;YACtF,4EAA4E;YAC5E,0DAA0D;SAC3D;KACF;IACD,OAAO,EAAE;QACP,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,oBAAoB,EAAE,QAAQ,EAAE,IAAI;QACnE,KAAK,EAAE;YACL,4FAA4F;YAC5F,8EAA8E;YAC9E,gEAAgE;YAChE,mEAAmE;SACpE;KACF;IACD,aAAa,EAAE;QACb,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe;QAC9C,KAAK,EAAE;YACL,+CAA+C;YAC/C,4DAA4D;YAC5D,uDAAuD;SACxD;KACF;IACD,IAAI,EAAE;QACJ,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM;QAChC,KAAK,EAAE;YACL,iFAAiF;YACjF,0EAA0E;YAC1E,qDAAqD;SACtD;KACF;IACD,aAAa,EAAE;QACb,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW;QACrC,KAAK,EAAE;YACL,gFAAgF;YAChF,kGAAkG;YAClG,8EAA8E;YAC9E,iEAAiE;SAClE;KACF;IACD,WAAW,EAAE;QACX,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,iBAAiB;QAC3C,KAAK,EAAE;YACL,0FAA0F;YAC1F,kEAAkE;SACnE;KACF;IACD,UAAU,EAAE;QACV,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe;QACzC,KAAK,EAAE;YACL,2DAA2D;YAC3D,+EAA+E;SAChF;KACF;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY;QACvC,KAAK,EAAE;YACL,4EAA4E;YAC5E,0DAA0D;YAC1D,4CAA4C;SAC7C;KACF;IACD,SAAS,EAAE;QACT,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,gBAAgB;QAC/C,KAAK,EAAE;YACL,uEAAuE;YACvE,kEAAkE;SACnE;KACF;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,mBAAmB;QAC9C,KAAK,EAAE;YACL,
|
|
1
|
+
{"version":3,"file":"polish.js","sourceRoot":"","sources":["../../src/data/polish.ts"],"names":[],"mappings":"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"}
|
package/dist/data/rules.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export declare const CODING_STANDARDS = "# AstralKit Coding Standards\n\n## Rule Zero \u2014 Library-First Principle\nBefore writing ANY UI, call `search_components` to check if the library already has it. If a match\nexists: `install_component` \u2192 import \u2192 RE-CONTENT (swap placeholder copy, nav items, logo, sample\ndata for the app's real content). Hand-writing a component the library already provides is a failure\n\u2014 even if your hand-written version is token-compliant. The library sets the quality bar:\n- 3x\u20135x type size jumps between headings and body (not subtle increments)\n- Weight pairs: bold (700\u2013800) heroes, semibold (600) titles, medium (500) descriptions\n- Premium effects (`ak-card-glow`, `ak-mesh-*`, `ak-material-surface`) where appropriate\n- 60-30-10 color restraint (60% neutral, 30% secondary, 10% accent)\n- Zero external CSS \u2014 every visual property on the element's `className`\nIf NOTHING fits exactly: start from the CLOSEST recipe and modify it \u2014 never from a blank file.\n\n## Setup\n- Package: `astralkit` (npm)\n- CSS: `@import \"astralkit/theme\"; @import \"astralkit/utilities\";` (after Tailwind imports)\n- Tailwind v3 plugin: `require('astralkit/tailwind.cjs')` in tailwind.config\n- Tailwind v4: `@import \"astralkit/theme-v4\"; @import \"astralkit/utilities\";`\n- Icons: `@phosphor-icons/react` exclusively. Never Lucide, Heroicons, or inline SVGs.\n- Fonts: Inter (body), DM Serif Display (display), JetBrains Mono (code)\n\n## Token-First Rule\nALWAYS use `ak-*` tokens. NEVER use arbitrary bracket values.\n```tsx\n// CORRECT\n<div className=\"p-ak-3 gap-ak-2 text-ak-base rounded-ak-lg\">\n// WRONG \u2014 arbitrary values silently collapse in Tailwind v4\n<div className=\"p-[1.5rem] gap-[1rem] text-[16px] rounded-[0.75rem]\">\n```\n\n## Semantic Colors \u2014 No Raw Tailwind\n```tsx\n// CORRECT: bg-ak-surface, text-ak-text, border-ak-border, bg-ak-primary\n// WRONG: bg-gray-50, text-gray-900, border-gray-200, bg-blue-600\n```\n\n## \u26A0 The AI Sizing Bias \u2014 you have it; counteract it deliberately\nAI coding models systematically undersize text and icons \u2014 the training corpus is dominated by dense 12-14px admin UI and shadcn examples where text-sm is \"body\" and 16px is \"icon\". The statistical default IS the bug. Countermeasures, in order:\n1. **When uncertain, size UP one step \u2014 never down.** Your instinct to shrink is the bias talking.\n2. **Build hierarchy from the TOP down.** Set the largest text first (page title, hero display), then derive downward \u2014 body lands at 16px naturally. NEVER create hierarchy by shrinking secondary text below the floor (body 14 \u2192 meta 12 \u2192 caption 10 is the classic downward spiral).\n3. **Role ladder, not vibes:** hero/display \u2192 text-ak-5xl..7xl \u00B7 page title \u2192 text-ak-3xl/4xl semibold \u00B7 section/card title \u2192 text-ak-xl/2xl semibold \u00B7 body \u2192 text-ak-base (16px, THE FLOOR) \u00B7 secondary/meta \u2192 text-ak-sm (14px) medium \u00B7 text-ak-xs (12px) \u2192 tabular data annotations, legal, chart axes ONLY \u00B7 below 12px \u2192 almost never (it has legitimate uses, but they are rare and deliberate \u2014 dataviz tick labels, print fine-print).\n4. **Icons: 20-24px for anything meaningful** (nav, list leading icons, section markers); 16px only for inline chevrons and meta glyphs. size={14} or smaller on a standalone icon is a bug.\n5. **Measure, don't trust yourself:** audit_page reports a rendered font-size histogram \u2014 any visible text under 12px is an ERROR, 12-13px gets flagged for review. Run it; your eyes-in-code cannot feel size.\n\n## Typography \u2014 16px Floor\n- Body text, descriptions, nav items, table cells: `text-ak-base` (16px) minimum\n- UI text: `font-medium` minimum \u2014 `font-normal` is for long-form prose only\n- Labels/badges: `text-ak-sm` (14px) or `text-ak-xs` (12px uppercase) acceptable\n- Helper/error text: `text-ak-sm` (14px) is the only exception\n\n## Spacing \u2014 ak-* Tokens Only\n```tsx\n// CORRECT: p-ak-3, gap-ak-2, mb-ak-1_5\n// WRONG: p-6, gap-4, mb-3\n```\n\n## Icons \u2014 Phosphor Only\n```tsx\nimport { House, Gear } from '@phosphor-icons/react'\n<House size={20} aria-hidden=\"true\" />\n```\n**Size floor:** meaningful icons (nav items, list/row leading icons, section markers, toggles' labels) are **20-24px** \u2014 16px icons beside 16px text read as clutter and fail comfortable-viewing accessibility. 16px is only for dense inline affordances (chevrons inside a button, meta-row glyphs). When an icon anchors a row the user scans, size it 24px.\n\n## No Inline Styles, No External CSS for Styling\nUse Tailwind `ak-*` utility classes on the element's `className`. `style={{}}` only for\ngenuinely data-driven values (dynamic chart heights, computed percentages, map coordinates).\n**NEVER write visual styling to CSS files** (globals.css, page.css, component.css, etc.) \u2014\nthis includes `var(--color-ak-*)`, `var(--spacing-ak-*)`, or any other CSS custom property\nreference. If you find yourself writing `.my-card { background: var(--color-ak-surface) }`,\nyou are doing it wrong \u2014 write `className=\"bg-ak-surface\"` on the element instead.\nIf the source already has external stylesheets with visual rules, EXTRACT the properties,\nconvert each to the nearest `ak-*` utility class (see the crosswalk in get_design_tokens),\napply the classes to the JSX elements, DELETE the stylesheet, and remove the import.\n**globals.css is for theme/utilities imports + optional palette overrides only** \u2014 never\nfor component styling.\n\n## No Shadows on Panels/Dropdowns \u2014 Borders Only\nUse `border border-ak-border`. Reserve shadows for modals and elevated cards.\n\n## Motion \u2014 Framer Motion + CSS + Lenis (GSAP not allowed)\nFramer Motion (the MIT `motion` package) IS allowed. Prefer the AstralKit presets from\n`astralkit/motion` (tuned to the motion tokens, reduced-motion-safe). CSS animations are\nalso fine (durations/easings via `duration-ak-*`, `ease-ak-spring`/`bounce`). Use Lenis for\nsmooth scroll. ALWAYS honor `prefers-reduced-motion`. **GSAP is NOT allowed** (license).\n```tsx\nimport { motion, useReducedMotion } from 'motion/react'\nimport { fadeInUp, withReducedMotion } from 'astralkit/motion'\nconst reduced = useReducedMotion()\n<motion.div initial=\"hidden\" animate=\"show\" variants={withReducedMotion(fadeInUp, reduced)} />\n```\n\n## Premium Polish \u2014 Use the Effect Toolkit (with taste)\nAstralKit ships CSS-only premium effects \u2014 reach for them so screens feel designed, not generic:\n- Depth/glow: `ak-card-glow`, `ak-ambient-glow`, `ak-spotlight-card`, `ak-gradient-border`, `ak-text-glow`, `ak-surface-raised`\n- Backgrounds: `ak-mesh-light` / `ak-mesh-dark` / `ak-mesh-astral` (mesh gradients)\n- Motion accents (CSS): `ak-float`, `ak-scroll-fade`, `ak-section-fade`, `ak-sheen`, `ak-press` (tap feedback)\n- Color: tasteful accent (60-30-10); colorful charts use `ak-chart-1`..`ak-chart-6`; curated palettes via `astralkit/palettes`\n- Icons: Phosphor `weight=\"duotone\"` reads richer for feature/marketing icons\n\n### Effect guardrails (use the RIGHT effect on the RIGHT surface)\n- **Glows need dark surfaces.** `ak-text-glow`, `ak-ambient-glow`, and `ak-card-glow` read correctly as LIGHT-on-DARK. On a light background with dark text they look like a muddy smudge \u2014 **do NOT put text-glow on dark text / light backgrounds.**\n- **For dramatic/marketing heroes, go dark.** Add the `dark` class to the section root + `ak-mesh-dark` (tokens auto-flip to dark), light text, and a gradient accent word. This reads more premium than a light hero.\n- **Gradient text accent** (instead of glow): `<span className=\"bg-gradient-to-r from-ak-primary to-ak-info bg-clip-text text-transparent\">word</span>`.\n- Don't stack many effects on one element; one accent treatment per focal point.\n\n## Layout primitives \u2014 don't fight responsive display\n`ak-stack`, `ak-cluster`, `ak-grid`, `ak-switcher` SET `display` (flex/grid) and are unlayered, so they OVERRIDE Tailwind's responsive display utilities (`md:hidden`, `lg:block`, `sm:hidden`). Putting a responsive display toggle on the SAME element silently fails (e.g. a mobile accordion stays visible on desktop):\n```tsx\n// WRONG \u2014 ak-stack's display:flex beats md:hidden, so it never hides\n<div className=\"md:hidden ak-stack\">\u2026</div>\n// RIGHT \u2014 wrap: toggle on the outer element, primitive inside\n<div className=\"md:hidden\"><div className=\"ak-stack\">\u2026</div></div>\n// or use plain flex/grid when you need to toggle visibility\n<div className=\"md:hidden flex flex-col\">\u2026</div>\n```\n\n## Breakpoints \u2014 collapse where content crushes, not at arbitrary md/lg\nThe breakpoint belongs where the content STARTS to crush, which is usually EARLIER than you think. Audit at three widths (1440 / 768 / 390) \u2014 768 is where late-breakpoint bugs live: multi-column grids squeezed to unreadable, toggle columns eating label width, sidebars pinning content into a sliver. If anything is cramped at 768, move the collapse up (`lg:` instead of `md:`, or a custom `min-[960px]:`). On mobile, navigation must become a REAL mobile pattern: hamburger + Radix Dialog side-sheet, or a bottom tab bar (2-3 primary destinations + a \"More\" trigger opening a Radix Sheet) \u2014 a shrunken or vanished desktop nav is a failure.\n\n## Charts \u2014 readable AND rendered (recipe)\nUse the colorful `ak-chart-*` tokens with solid fills (not faint `ak-primary` tints). **Percentage bar heights only resolve if the container has a DEFINITE height** \u2014 a common bug is `min-height` + `items-end`, which collapses the bars to zero. Use this pattern:\n```tsx\n{/* DEFINITE height (h-56) + stretched columns so %-height bars resolve */}\n<div className=\"flex h-56 items-stretch gap-ak-1\">\n {data.map((v, i) => (\n <div key={i} className=\"group flex flex-1 flex-col justify-end gap-ak-1\">\n <div\n className={(i === data.length - 1 ? 'bg-ak-primary' : 'bg-ak-chart-1') + ' w-full rounded-ak-md'}\n style={{ height: `${Math.round((v / max) * 100)}%` }} /* sanctioned data-driven inline style */\n role=\"img\" aria-label={`${labels[i]}: ${v}`}\n />\n <span className=\"text-ak-xs text-ak-text-muted\">{labels[i]}</span>\n </div>\n ))}\n</div>\n```\n\n## Touch Targets \u2014 48px Minimum\n- Buttons: `min-h-[3rem]` + `cursor-pointer`\n- Form inputs: `h-14` (56px)\n\n## Empty States \u2014 Every Data Container\nEvery list, table, or feed must handle: Loading \u2192 Error \u2192 Empty \u2192 Data.\nEmpty states need: icon, title, description, CTA.\n\n## Error Handling \u2014 Never Show Raw Errors\nUser-facing errors need: title (jargon-free), description, action (Retry/Go Back).\n\n## cn() Utility\n```tsx\nimport { cn } from '@/lib/utils'\n<div className={cn(\"p-ak-3\", isActive && \"bg-ak-primary\")}>\n```\n\n## Theming Grammar \u2014 M3 Role System (60-30-10)\nEvery fill must use a ROLE, never resolve \"what color is this\" yourself:\n- **CTAs + binary on-states** (buttons, checked checkbox, toggle-ON): `bg-ak-primary text-ak-on-primary hover:bg-ak-primary-hover` \u2014 NEVER `bg-ak-text` for interactive fills.\n- **Selection-among-options** (active tab/segment/chip/nav item): `bg-ak-secondary text-ak-on-secondary`; subtle selected rows/nav: `bg-ak-secondary-container text-ak-on-secondary-container`.\n- **Selected-not-pressed cards**: `bg-ak-primary-container border-ak-primary`.\n- **Inverted/dark panels** (terminals, dark rails, dark tooltips, promo cards): `bg-ak-inverse-surface text-ak-inverse-on-surface` \u2014 NEVER `bg-ak-text`, `bg-ak-neutral-900 text-white`, or raw `bg-black`/hex.\n- **Surfaces**: page canvas `bg-ak-surface` \u2192 paper cards/inputs `bg-ak-surface-container-lowest` (or legacy `bg-ak-bg`/`bg-ak-elevated`) \u2192 wells/tracks `bg-ak-surface-container` (`-high`/`-highest` deeper). Borders: `border-ak-outline-variant` (hairline) / `border-ak-outline`.\n- **Overlays**: `bg-ak-scrim`. **Status**: `ak-error(-container)`/`ak-success`/`ak-warning`/`ak-info` + their `-text`/`on-` partners.\n- Non-interactive emphasis ink pills may keep `bg-ak-text text-ak-bg`. Opacity washes (`bg-ak-text/10`) stay neutral. Content colors (palette swatches, chart data) are exempt.\nDefault theme: primary is black, secondary falls back to primary \u2014 monochrome by default, fully colorable by any theme.\n\n## Gotchas \u2014 Silent Failures\nThese will NOT throw errors. The UI will silently break and you won't know unless you look:\n- **Underscore, not dot** \u2014 `ak-1_5`, NOT `ak-1.5`. Dot notation silently collapses to zero in Tailwind v4. Your spacing/padding will render as 0.\n- **No `/opacity` on ak-* tokens** \u2014 `bg-ak-warning/30` renders transparent, not faded. Use the `-subtle` variant (`bg-ak-warning-subtle`). The ONLY sanctioned opacity idiom is `inverse-on-surface/NN`.\n- **Non-existent ak-* class names render nothing** \u2014 no error, no warning, just invisible. Always verify token names exist in the token reference (get_design_tokens).\n- **Portalled overlays escape theme scope** \u2014 Radix portals mount outside your `data-ak-theme` wrapper. Wrap portalled content in a theme provider or set the attribute on the portal container.\n- **Avatar sizing** \u2014 use `size-ak-avatar-sm` / `size-ak-avatar-md` / `size-ak-avatar-lg` ONLY. `h-ak-avatar-lg` or `w-ak-avatar-md` do NOT exist.\n- **Layout primitives override display** \u2014 `ak-stack`, `ak-cluster`, `ak-grid` set display and are unlayered, so they BEAT responsive toggles (`md:hidden`) on the same element. Wrap the primitive in a toggler div instead.\n\n## Preflight Gates \u2014 validate_code Is Not a Compiler\n`validate_code` checks AstralKit conventions. It does NOT catch syntax errors, type errors, or\nruntime bugs. After validate_code passes, you MUST also run:\n1. `npx tsc --noEmit` \u2014 type-check\n2. `npm run build` (or `next build`) \u2014 full build\n3. Runtime verify \u2014 `next start` + check the actual URL renders correctly\n4. Visual verify \u2014 `verify_visual` or `screenshot_ui` (premium), or use your own browser tools\n`npm run dev` working proves nothing \u2014 it skips type-checking and many build errors.\n";
|
|
1
|
+
export declare const CODING_STANDARDS = "# AstralKit Coding Standards\n\n## Rule Zero \u2014 Library-First Principle\nBefore writing ANY UI, call `search_components` to check if the library already has it. If a match\nexists: `install_component` \u2192 import \u2192 RE-CONTENT (swap placeholder copy, nav items, logo, sample\ndata for the app's real content). Hand-writing a component the library already provides is a failure\n\u2014 even if your hand-written version is token-compliant. The library sets the quality bar:\n- 3x\u20135x type size jumps between headings and body (not subtle increments)\n- Weight pairs: bold (700\u2013800) heroes, semibold (600) titles, medium (500) descriptions\n- Premium effects (`ak-card-glow`, `ak-mesh-*`, `ak-material-surface`) where appropriate\n- 60-30-10 color restraint (60% neutral, 30% secondary, 10% accent)\n- Zero external CSS \u2014 every visual property on the element's `className`\nIf NOTHING fits exactly: start from the CLOSEST recipe and modify it \u2014 never from a blank file.\n\n## Setup\n- Package: `astralkit` (npm)\n- CSS: `@import \"astralkit/theme\"; @import \"astralkit/utilities\";` (after Tailwind imports)\n- Tailwind v3 plugin: `require('astralkit/tailwind.cjs')` in tailwind.config\n- Tailwind v4: `@import \"astralkit/theme-v4\"; @import \"astralkit/utilities\";`\n- Icons: `@phosphor-icons/react` exclusively. Never Lucide, Heroicons, or inline SVGs.\n- Fonts: Inter (body), DM Serif Display (display), JetBrains Mono (code)\n\n## Token-First Rule\nALWAYS use `ak-*` tokens. NEVER use arbitrary bracket values.\n```tsx\n// CORRECT\n<div className=\"p-ak-6 gap-ak-4 text-ak-base rounded-ak-lg\">\n// WRONG \u2014 arbitrary values silently collapse in Tailwind v4\n<div className=\"p-[1.5rem] gap-[1rem] text-[16px] rounded-[0.75rem]\">\n```\n\n## Semantic Colors \u2014 No Raw Tailwind\n```tsx\n// CORRECT: bg-ak-surface, text-ak-text, border-ak-border, bg-ak-primary\n// WRONG: bg-gray-50, text-gray-900, border-gray-200, bg-blue-600\n```\n\n## \u26A0 The AI Sizing Bias \u2014 you have it; counteract it deliberately\nAI coding models systematically undersize text and icons \u2014 the training corpus is dominated by dense 12-14px admin UI and shadcn examples where text-sm is \"body\" and 16px is \"icon\". The statistical default IS the bug. Countermeasures, in order:\n1. **When uncertain, size UP one step \u2014 never down.** Your instinct to shrink is the bias talking.\n2. **Build hierarchy from the TOP down.** Set the largest text first (page title, hero display), then derive downward \u2014 body lands at 16px naturally. NEVER create hierarchy by shrinking secondary text below the floor (body 14 \u2192 meta 12 \u2192 caption 10 is the classic downward spiral).\n3. **Role ladder, not vibes:** hero/display \u2192 text-ak-5xl..7xl \u00B7 page title \u2192 text-ak-3xl/4xl semibold \u00B7 section/card title \u2192 text-ak-xl/2xl semibold \u00B7 body \u2192 text-ak-base (16px, THE FLOOR) \u00B7 secondary/meta \u2192 text-ak-sm (14px) medium \u00B7 text-ak-xs (12px) \u2192 tabular data annotations, legal, chart axes ONLY \u00B7 below 12px \u2192 almost never (it has legitimate uses, but they are rare and deliberate \u2014 dataviz tick labels, print fine-print).\n4. **Icons: 20-24px for anything meaningful** (nav, list leading icons, section markers); 16px only for inline chevrons and meta glyphs. size={14} or smaller on a standalone icon is a bug.\n5. **Measure, don't trust yourself:** audit_page reports a rendered font-size histogram \u2014 any visible text under 12px is an ERROR, 12-13px gets flagged for review. Run it; your eyes-in-code cannot feel size.\n\n## Typography \u2014 16px Floor\n- Body text, descriptions, nav items, table cells: `text-ak-base` (16px) minimum\n- UI text: `font-medium` minimum \u2014 `font-normal` is for long-form prose only\n- Labels/badges: `text-ak-sm` (14px) or `text-ak-xs` (12px uppercase) acceptable\n- Helper/error text: `text-ak-sm` (14px) is the only exception\n\n## Spacing \u2014 ak-* Tokens Only\n```tsx\n// CORRECT: p-ak-6, gap-ak-4, mb-ak-3\n// WRONG: p-6, gap-4, mb-3\n```\n\n## Icons \u2014 Phosphor Only\n```tsx\nimport { House, Gear } from '@phosphor-icons/react'\n<House size={20} aria-hidden=\"true\" />\n```\n**Size floor:** meaningful icons (nav items, list/row leading icons, section markers, toggles' labels) are **20-24px** \u2014 16px icons beside 16px text read as clutter and fail comfortable-viewing accessibility. 16px is only for dense inline affordances (chevrons inside a button, meta-row glyphs). When an icon anchors a row the user scans, size it 24px.\n\n## No Inline Styles, No External CSS for Styling\nUse Tailwind `ak-*` utility classes on the element's `className`. `style={{}}` only for\ngenuinely data-driven values (dynamic chart heights, computed percentages, map coordinates).\n**NEVER write visual styling to CSS files** (globals.css, page.css, component.css, etc.) \u2014\nthis includes `var(--color-ak-*)`, `var(--spacing-ak-*)`, or any other CSS custom property\nreference. If you find yourself writing `.my-card { background: var(--color-ak-surface) }`,\nyou are doing it wrong \u2014 write `className=\"bg-ak-surface\"` on the element instead.\nIf the source already has external stylesheets with visual rules, EXTRACT the properties,\nconvert each to the nearest `ak-*` utility class (see the crosswalk in get_design_tokens),\napply the classes to the JSX elements, DELETE the stylesheet, and remove the import.\n**globals.css is for theme/utilities imports + optional palette overrides only** \u2014 never\nfor component styling.\n\n## No Shadows on Panels/Dropdowns \u2014 Borders Only\nUse `border border-ak-border`. Reserve shadows for modals and elevated cards.\n\n## Motion \u2014 Framer Motion + CSS + Lenis (GSAP not allowed)\nFramer Motion (the MIT `motion` package) IS allowed. Prefer the AstralKit presets from\n`astralkit/motion` (tuned to the motion tokens, reduced-motion-safe). CSS animations are\nalso fine (durations/easings via `duration-ak-*`, `ease-ak-spring`/`bounce`). Use Lenis for\nsmooth scroll. ALWAYS honor `prefers-reduced-motion`. **GSAP is NOT allowed** (license).\n```tsx\nimport { motion, useReducedMotion } from 'motion/react'\nimport { fadeInUp, withReducedMotion } from 'astralkit/motion'\nconst reduced = useReducedMotion()\n<motion.div initial=\"hidden\" animate=\"show\" variants={withReducedMotion(fadeInUp, reduced)} />\n```\n\n## Premium Polish \u2014 Use the Effect Toolkit (with taste)\nAstralKit ships CSS-only premium effects \u2014 reach for them so screens feel designed, not generic:\n- Depth/glow: `ak-card-glow`, `ak-ambient-glow`, `ak-spotlight-card`, `ak-gradient-border`, `ak-text-glow`, `ak-surface-raised`\n- Backgrounds: `ak-mesh-light` / `ak-mesh-dark` / `ak-mesh-astral` (mesh gradients)\n- Motion accents (CSS): `ak-float`, `ak-scroll-fade`, `ak-section-fade`, `ak-sheen`, `ak-press` (tap feedback)\n- Color: tasteful accent (60-30-10); colorful charts use `ak-chart-1`..`ak-chart-6`; curated palettes via `astralkit/palettes`\n- Icons: Phosphor `weight=\"duotone\"` reads richer for feature/marketing icons\n\n### Effect guardrails (use the RIGHT effect on the RIGHT surface)\n- **Glows need dark surfaces.** `ak-text-glow`, `ak-ambient-glow`, and `ak-card-glow` read correctly as LIGHT-on-DARK. On a light background with dark text they look like a muddy smudge \u2014 **do NOT put text-glow on dark text / light backgrounds.**\n- **For dramatic/marketing heroes, go dark.** Add the `dark` class to the section root + `ak-mesh-dark` (tokens auto-flip to dark), light text, and a gradient accent word. This reads more premium than a light hero.\n- **Gradient text accent** (instead of glow): `<span className=\"bg-gradient-to-r from-ak-primary to-ak-info bg-clip-text text-transparent\">word</span>`.\n- Don't stack many effects on one element; one accent treatment per focal point.\n\n## Layout primitives \u2014 don't fight responsive display\n`ak-stack`, `ak-cluster`, `ak-grid`, `ak-switcher` SET `display` (flex/grid) and are unlayered, so they OVERRIDE Tailwind's responsive display utilities (`md:hidden`, `lg:block`, `sm:hidden`). Putting a responsive display toggle on the SAME element silently fails (e.g. a mobile accordion stays visible on desktop):\n```tsx\n// WRONG \u2014 ak-stack's display:flex beats md:hidden, so it never hides\n<div className=\"md:hidden ak-stack\">\u2026</div>\n// RIGHT \u2014 wrap: toggle on the outer element, primitive inside\n<div className=\"md:hidden\"><div className=\"ak-stack\">\u2026</div></div>\n// or use plain flex/grid when you need to toggle visibility\n<div className=\"md:hidden flex flex-col\">\u2026</div>\n```\n\n## Breakpoints \u2014 collapse where content crushes, not at arbitrary md/lg\nThe breakpoint belongs where the content STARTS to crush, which is usually EARLIER than you think. Audit at three widths (1440 / 768 / 390) \u2014 768 is where late-breakpoint bugs live: multi-column grids squeezed to unreadable, toggle columns eating label width, sidebars pinning content into a sliver. If anything is cramped at 768, move the collapse up (`lg:` instead of `md:`, or a custom `min-[960px]:`). On mobile, navigation must become a REAL mobile pattern: hamburger + Radix Dialog side-sheet, or a bottom tab bar (2-3 primary destinations + a \"More\" trigger opening a Radix Sheet) \u2014 a shrunken or vanished desktop nav is a failure.\n\n## Charts \u2014 readable AND rendered (recipe)\nUse the colorful `ak-chart-*` tokens with solid fills (not faint `ak-primary` tints). **Percentage bar heights only resolve if the container has a DEFINITE height** \u2014 a common bug is `min-height` + `items-end`, which collapses the bars to zero. Use this pattern:\n```tsx\n{/* DEFINITE height (h-56) + stretched columns so %-height bars resolve */}\n<div className=\"flex h-56 items-stretch gap-ak-2\">\n {data.map((v, i) => (\n <div key={i} className=\"group flex flex-1 flex-col justify-end gap-ak-2\">\n <div\n className={(i === data.length - 1 ? 'bg-ak-primary' : 'bg-ak-chart-1') + ' w-full rounded-ak-md'}\n style={{ height: `${Math.round((v / max) * 100)}%` }} /* sanctioned data-driven inline style */\n role=\"img\" aria-label={`${labels[i]}: ${v}`}\n />\n <span className=\"text-ak-xs text-ak-text-muted\">{labels[i]}</span>\n </div>\n ))}\n</div>\n```\n\n## Touch Targets \u2014 48px Minimum\n- Buttons: `min-h-[3rem]` + `cursor-pointer`\n- Form inputs: `h-14` (56px)\n\n## Empty States \u2014 Every Data Container\nEvery list, table, or feed must handle: Loading \u2192 Error \u2192 Empty \u2192 Data.\nEmpty states need: icon, title, description, CTA.\n\n## Error Handling \u2014 Never Show Raw Errors\nUser-facing errors need: title (jargon-free), description, action (Retry/Go Back).\n\n## cn() Utility\n```tsx\nimport { cn } from '@/lib/utils'\n<div className={cn(\"p-ak-6\", isActive && \"bg-ak-primary\")}>\n```\n\n## Theming Grammar \u2014 M3 Role System (60-30-10)\nEvery fill must use a ROLE, never resolve \"what color is this\" yourself:\n- **CTAs + binary on-states** (buttons, checked checkbox, toggle-ON): `bg-ak-primary text-ak-on-primary hover:bg-ak-primary-hover` \u2014 NEVER `bg-ak-text` for interactive fills.\n- **Selection-among-options** (active tab/segment/chip/nav item): `bg-ak-secondary text-ak-on-secondary`; subtle selected rows/nav: `bg-ak-secondary-container text-ak-on-secondary-container`.\n- **Selected-not-pressed cards**: `bg-ak-primary-container border-ak-primary`.\n- **Inverted/dark panels** (terminals, dark rails, dark tooltips, promo cards): `bg-ak-inverse-surface text-ak-inverse-on-surface` \u2014 NEVER `bg-ak-text`, `bg-ak-neutral-900 text-white`, or raw `bg-black`/hex.\n- **Surfaces**: page canvas `bg-ak-surface` \u2192 paper cards/inputs `bg-ak-surface-container-lowest` (or legacy `bg-ak-bg`/`bg-ak-elevated`) \u2192 wells/tracks `bg-ak-surface-container` (`-high`/`-highest` deeper). Borders: `border-ak-outline-variant` (hairline) / `border-ak-outline`.\n- **Overlays**: `bg-ak-scrim`. **Status**: `ak-error(-container)`/`ak-success`/`ak-warning`/`ak-info` + their `-text`/`on-` partners.\n- Non-interactive emphasis ink pills may keep `bg-ak-text text-ak-bg`. Opacity washes (`bg-ak-text/10`) stay neutral. Content colors (palette swatches, chart data) are exempt.\nDefault theme: primary is black, secondary falls back to primary \u2014 monochrome by default, fully colorable by any theme.\n\n## Gotchas \u2014 Silent Failures\nThese will NOT throw errors. The UI will silently break and you won't know unless you look:\n- **Underscore, not dot** \u2014 `ak-1_5`, NOT `ak-1.5`. Dot notation silently collapses to zero in Tailwind v4. Your spacing/padding will render as 0.\n- **No `/opacity` on ak-* tokens** \u2014 `bg-ak-warning/30` renders transparent, not faded. Use the `-subtle` variant (`bg-ak-warning-subtle`). The ONLY sanctioned opacity idiom is `inverse-on-surface/NN`.\n- **Non-existent ak-* class names render nothing** \u2014 no error, no warning, just invisible. Always verify token names exist in the token reference (get_design_tokens).\n- **Portalled overlays escape theme scope** \u2014 Radix portals mount outside your `data-ak-theme` wrapper. Wrap portalled content in a theme provider or set the attribute on the portal container.\n- **Avatar sizing** \u2014 use `size-ak-avatar-sm` / `size-ak-avatar-md` / `size-ak-avatar-lg` ONLY. `h-ak-avatar-lg` or `w-ak-avatar-md` do NOT exist.\n- **Layout primitives override display** \u2014 `ak-stack`, `ak-cluster`, `ak-grid` set display and are unlayered, so they BEAT responsive toggles (`md:hidden`) on the same element. Wrap the primitive in a toggler div instead.\n\n## Preflight Gates \u2014 validate_code Is Not a Compiler\n`validate_code` checks AstralKit conventions. It does NOT catch syntax errors, type errors, or\nruntime bugs. After validate_code passes, you MUST also run:\n1. `npx tsc --noEmit` \u2014 type-check\n2. `npm run build` (or `next build`) \u2014 full build\n3. Runtime verify \u2014 `next start` + check the actual URL renders correctly\n4. Visual verify \u2014 `verify_visual` or `screenshot_ui` (premium), or use your own browser tools\n`npm run dev` working proves nothing \u2014 it skips type-checking and many build errors.\n";
|
|
2
2
|
//# sourceMappingURL=rules.d.ts.map
|
package/dist/data/rules.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/data/rules.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,
|
|
1
|
+
{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/data/rules.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,m+bAuL5B,CAAC"}
|