@fractaldesign/fractalstyler 0.0.0-stage → 0.9.0

package/skills/fractal-styler/references/tokens.md

@@ -0,0 +1,226 @@
+# Fractalstyler2 — Token Reference
+
+GENERATED FILE — do not edit. Emitted by `scripts/update-registry.js`
+from `_00_tokens.sass` (light/dark mixins + `:root`) and the shadow specs in
+`_00_config.sass`.
+
+Every `--space-*` step is a class family: if `--space-md` exists, so do
+`.gap-md`, `.pad-md` and `.mar-md` (plus the `.px`/`.py`/`.pt`… sides).
+There is no second vocabulary to learn.
+
+## Type Scale
+
+Fixed rem rungs up to base, then compounded by `--text-scaling` (1.25).
+
+| Token | Class | Value |
+|:---|:---|:---|
+| `--text-xs` | `.text-xs` | `0.67rem` |
+| `--text-sm` | `.text-sm` | `0.75rem` |
+| `--text-md` | `.text-md` | `0.875rem` |
+| `--text-bs` | `.text-bs` | `1rem` |
+| `--text-lg` | `.text-lg` | `calc(var(--text-bs) * var(--text-scaling))` |
+| `--text-xl` | `.text-xl` | `calc(var(--text-lg) * var(--text-scaling))` |
+| `--text-2xl` | `.text-2xl` | `calc(var(--text-xl) * var(--text-scaling))` |
+| `--text-3xl` | `.text-3xl` | `calc(var(--text-2xl) * var(--text-scaling))` |
+| `--text-4xl` | `.text-4xl` | `calc(var(--text-3xl) * var(--text-scaling))` |
+| `--text-5xl` | `.text-5xl` | `calc(var(--text-4xl) * var(--text-scaling))` |
+
+| Token | Class | Value |
+|:---|:---|:---|
+| `--text-scaling` | — | `1.25` |
+
+## Space Scale
+
+`--unit-space` (0.25rem) times a step multiplier. Every step feeds the
+gap/pad/mar families in L1.
+
+| Token | Class | Value |
+|:---|:---|:---|
+| `--unit-space` | — | `0.25rem` |
+
+| Token | Class | Value |
+|:---|:---|:---|
+| `--space-xs` | `.gap-xs` `.pad-xs` `.mar-xs` + sides | `var(--unit-space)` |
+| `--space-sm` | `.gap-sm` `.pad-sm` `.mar-sm` + sides | `calc(var(--unit-space) * 2)` |
+| `--space-md` | `.gap-md` `.pad-md` `.mar-md` + sides | `calc(var(--unit-space) * 3)` |
+| `--space-bs` | `.gap-bs` `.pad-bs` `.mar-bs` + sides | `calc(var(--unit-space) * 4)` |
+| `--space-lg` | `.gap-lg` `.pad-lg` `.mar-lg` + sides | `calc(var(--unit-space) * 6)` |
+| `--space-xl` | `.gap-xl` `.pad-xl` `.mar-xl` + sides | `calc(var(--unit-space) * 8)` |
+| `--space-2xl` | `.gap-2xl` `.pad-2xl` `.mar-2xl` + sides | `calc(var(--unit-space) * 12)` |
+| `--space-3xl` | `.gap-3xl` `.pad-3xl` `.mar-3xl` + sides | `calc(var(--unit-space) * 16)` |
+
+## Radius
+
+Six channels. Compositions read the tokens, never a literal radius.
+
+| Token | Class | Value |
+|:---|:---|:---|
+| `--radius-xs` | `.radius-xs` | `2px` |
+| `--radius-sm` | `.radius-sm` | `4px` |
+| `--radius-md` | `.radius-md` | `8px` |
+| `--radius-bs` | `.radius-bs` | `16px` |
+| `--radius-lg` | `.radius-lg` | `32px` |
+| `--radius-full` | `.radius-full` | `9999px` |
+
+## Control & Component Metrics
+
+Heights for inputs, selects and buttons; avatar and switch channels.
+
+| Token | Class | Value |
+|:---|:---|:---|
+| `--control-h-sm` | — | `21px` |
+| `--control-h-bs` | — | `32px` |
+| `--control-h-lg` | — | `38px` |
+| `--avatar-size` | — | `32px` |
+| `--switch-w` | — | `40px` |
+| `--switch-h` | — | `22px` |
+| `--switch-thumb` | — | `16px` |
+| `--height-sm` | `.h-sm` | `16px` |
+| `--height-md` | `.h-md` | `20px` |
+| `--height-bs` | `.h-bs` | `27px` |
+| `--height-lg` | `.h-lg` | `32px` |
+
+## Motion Language
+
+Durations, easings and the composed `--motion*` channels every transition reads.
+
+| Token | Class | Value |
+|:---|:---|:---|
+| `--transin1` | — | `cubic-bezier(0.470, 0.000, 0.745, 0.715)` |
+| `--transin2` | — | `cubic-bezier(0.550, 0.055, 0.675, 0.190)` |
+| `--transin3` | — | `cubic-bezier(0.755, 0.050, 0.855, 0.060)` |
+| `--transout1` | — | `cubic-bezier(0.390, 0.575, 0.565, 1.000)` |
+| `--transout2` | — | `cubic-bezier(0.215, 0.610, 0.355, 1.000)` |
+| `--transout3` | — | `cubic-bezier(0.230, 1.000, 0.320, 1.000)` |
+| `--speed0` | — | `50ms` |
+| `--speed1` | — | `90ms` |
+| `--speed2` | — | `140ms` |
+| `--speed3` | — | `220ms` |
+| `--motionin1` | — | `var(--speed0) var(--transin1)` |
+| `--motionout1` | — | `var(--speed1) var(--transout1)` |
+| `--motionin2` | — | `var(--speed2) var(--transin2)` |
+| `--motionout2` | — | `var(--speed2) var(--transout2)` |
+| `--motionin3` | — | `var(--speed3) var(--transin3)` |
+| `--motionout3` | — | `var(--speed3) var(--transout3)` |
+
+## Colour Roles
+
+Name the role, never the hex. Values shown are the light default;
+`[data-mode='dark']` remaps them via `=dark-theme-tokens`.
+
+| Token | Class | Value |
+|:---|:---|:---|
+| `--white-fixed` | `.text-white` | `#FFFFFF` |
+| `--black-fixed` | `.text-black` | `#171717` |
+| `--bg` | — | `#ffffff` |
+| `--bg-surface` | — | `#FBFBF9` |
+| `--bg-panel` | — | `#FBFBF9` |
+| `--bg-sunken` | — | `#F7F6F0` |
+| `--bg-raised` | — | `#F4F4F5` |
+| `--bg-extra` | — | `rgb(247, 248, 249)` |
+| `--bg-input` | — | `#f8f9fa` |
+| `--bg-button` | — | `#CED8D3` |
+| `--text-primary` | .text-primary | `#262627` |
+| `--text-secondary` | .text-secondary | `#777777` |
+| `--text-muted` | .text-muted | `#a3a4a7` |
+| `--text-inverse` | .text-inverse | `#ffffff` |
+| `--state-surface` | — | `#F2EFE9` |
+| `--state-hover` | — | `#ECE7DF` |
+| `--state-selected` | — | `#E4DFD5` |
+| `--border` | — | `#d8d8d8` |
+| `--border-subtle` | — | `#eceaea` |
+| `--border-strong` | — | `#cfcfcf` |
+| `--theme-color` | `.text-theme` | `#ff4400` |
+| `--theme-color-alt` | — | `#be2f00` |
+| `--theme-color-sub` | — | `#feb18a` |
+| `--success` | `.text-success` `.bg-success` | `#10B981` |
+| `--success-hover` | — | `#059669` |
+| `--warning` | `.text-warning` `.bg-warning` | `#F59E0B` |
+| `--warning-hover` | — | `#D97706` |
+| `--danger` | `.text-danger` `.bg-danger` | `#bf2a2a` |
+| `--danger-hover` | — | `#DC2626` |
+| `--info` | `.text-info` `.bg-info` | `#3B82F6` |
+| `--info-hover` | — | `#2563EB` |
+| `--ring` | — | `rgba(0, 127, 78, 0.35)` |
+
+## Elevation
+
+`--shadow-*` channels are what the `.shadow-*` classes read; `--shade-*` are
+loop-generated from `$shadow-specs` in `_00_config.sass` (rim + key + ambient).
+
+| Token | Class | Value |
+|:---|:---|:---|
+| `--shadow-color` | — | `15 13 42` |
+| `--shadow-rim` | — | `transparent` |
+| `--shadow-xs` | `.shadow-xs` | `0 1px 2px rgb(var(--shadow-color) / 0.14)` |
+| `--shadow-sm` | `.shadow-sm` | `0 1px 2px rgb(var(--shadow-color) / 0.10), 0 2px 4px rgb(var(--shadow-color) / 0.06)` |
+| `--shadow-md` | `.shadow-md` | `0 2px 4px rgb(var(--shadow-color) / 0.06), 0 8px 16px rgb(var(--shadow-color) / 0.06)` |
+| `--shadow-bs` | `.shadow-bs` | `0 2px 4px rgb(var(--shadow-color) / 0.06), 0 6px 14px rgb(var(--shadow-color) / 0.06)` |
+| `--shadow-lg` | `.shadow-lg` | `0 4px 8px rgb(var(--shadow-color) / 0.06), 0 12px 24px rgb(var(--shadow-color) / 0.06)` |
+| `--shadow-xl` | `.shadow-xl` | `0 8px 16px rgb(var(--shadow-color) / 0.06), 0 20px 36px rgb(var(--shadow-color) / 0.06)` |
+| `--shadow-2xl` | `.shadow-2xl` | `0 12px 24px rgb(var(--shadow-color) / 0.06), 0 28px 48px rgb(var(--shadow-color) / 0.06)` |
+| `--shadow-3xl` | `.shadow-3xl` | `0 16px 32px rgb(var(--shadow-color) / 0.06), 0 36px 64px rgb(var(--shadow-color) / 0.06)` |
+| `--shadow-umbra` | — | `rgb(0 0 0 / 0.50)` |
+| `--shade-xs` | — | `var(--shadow-rim), 0 1px 1px rgb(var(--shadow-color) / 0.14), 0 0px 0px rgb(var(--shadow-color) / 0.00)` |
+| `--shade-sm` | — | `var(--shadow-rim), 0 1px 2px rgb(var(--shadow-color) / 0.12), 0 1px 3px rgb(var(--shadow-color) / 0.02)` |
+| `--shade-md` | — | `var(--shadow-rim), 0 2px 4px rgb(var(--shadow-color) / 0.09), 0 3px 6px rgb(var(--shadow-color) / 0.04)` |
+| `--shade-bs` | — | `var(--shadow-rim), 0 2px 4px rgb(var(--shadow-color) / 0.06), 0 6px 14px rgb(var(--shadow-color) / 0.06)` |
+| `--shade-lg` | — | `var(--shadow-rim), 0 4px 8px rgb(var(--shadow-color) / 0.04), 0 12px 24px rgb(var(--shadow-color) / 0.08)` |
+| `--shade-xl` | — | `var(--shadow-rim), 0 6px 12px rgb(var(--shadow-color) / 0.03), 0 20px 36px rgb(var(--shadow-color) / 0.09)` |
+| `--shade-2xl` | — | `var(--shadow-rim), 0 8px 16px rgb(var(--shadow-color) / 0.02), 0 28px 48px rgb(var(--shadow-color) / 0.09)` |
+| `--shade-3xl` | — | `var(--shadow-rim), 0 12px 24px rgb(var(--shadow-color) / 0.02), 0 36px 64px rgb(var(--shadow-color) / 0.08)` |
+| `--shadow-color` | — | `15 13 42` |
+| `--shadow-rim` | — | `transparent` |
+
+## Fonts, Layout Constants & Page Chrome
+
+Font stacks plus the page geometry the shells and viewport classes read.
+
+| Token | Class | Value |
+|:---|:---|:---|
+| `--font-sans` | — | `"Timeless Sans", sans-serif` |
+| `--timeless-sans` | — | `"Timeless Sans", sans-serif` |
+| `--timeless-grotesk` | — | `"Timeless Grotesk", sans-serif` |
+| `--header-height` | — | `64px` |
+| `--footer-height` | — | `32px` |
+| `--fit-height` | — | `calc(var(--header-height) + var(--footer-height))` |
+| `--prose-clamp` | — | `65ch` |
+| `--content-clamp` | — | `1600px` |
+| `--app-inline` | — | `var(--space-lg)` |
+| `--card-min` | — | `240px` |
+| `--sidebar-width` | — | `280px` |
+| `--sidebar-width-left` | — | `280px` |
+| `--sidebar-width-right` | — | `280px` |
+| `--z-sticky` | — | `100` |
+| `--z-raised` | — | `200` |
+| `--z-modal` | — | `300` |
+| `--z-toast` | — | `500` |
+
+## Pop Colors
+
+Named accent literals. The `.orange1`…`.orange6` ink classes read
+`--orangepop*`; the green set is reserved for future use.
+
+| Token | Class | Value |
+|:---|:---|:---|
+| `--greenpop1` | — | `#70e000` |
+| `--greenpop2` | — | `#00df89` |
+| `--greenpop3` | — | `#69ff97` |
+| `--greenpop4` | — | `#00e676` |
+| `--orangepop1` | `.orange1` | `#ff7700` |
+| `--orangepop2` | `.orange2` | `#ff4400` |
+| `--orangepop3` | `.orange3` | `#ff0055` |
+| `--orangepop4` | `.orange4` | `#ff5e36` |
+| `--orangepop5` | `.orange5` | `#ff9966` |
+| `--orangepop6` | `.orange6` | `#ff9f1c` |
+
+## Modes & Attribute Axes
+
+`data-mode` on the root selects the token mixin: `light` (default) or `dark`.
+
+| Attribute | Where | Values | Effect |
+|:---|:---|:---|:---|
+| `data-mode` | `<html>` | `light` \| `dark` | Swaps `=light-theme-tokens` / `=dark-theme-tokens` |
+| `data-shape` | `.card`, `button` | `modern` \| `curved` \| `round` | Corner treatment of the component |
+| `data-variant` | `button` | `primary` \| `secondary` \| `soft` \| `outline` \| `ghost` \| `link` \| `destructive` | Paint variant of the button quartet |
+| `data-size` | `button` | `sm` \| `md` \| `bs` \| `lg` | Metrics variant of the button quartet |

package/skills/fractalstyler/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: fractalstyler
+description: Build, compose, modify, or audit UI interfaces using the closed Fractalstyler composition styling system. Use whenever authoring HTML, Svelte, Sass, CSS, or TS/JS components where new ad-hoc classes, scoped style blocks, inline styles, custom properties, or arbitrary CSS are strictly forbidden.
+---
+
+# Fractalstyler Styling System & Style Guard
+
+Operate within the `fractalstyler` registry as a **closed world**. Never invent a class or styling definition, even when the requested design is not immediately obvious.
+
+## Mandatory Agent Workflow
+
+1. **Consult the Registry First**:
+   Read `REGISTRY.md` or `registry.json`. Search for existing utility classes, container bases, layouts, and shells before writing any markup.
+2. **Review Recipes**:
+   Check `data/recipes.json` for verified canonical compositions (segmented controls, search input bars, metrics grids, action rows, switches, modals).
+3. **Compose Only from Verified Classes**:
+   - Containers: `.box` (column), `.row` (horizontal), `.grid` (CSS grid).
+   - Physical Alignment: `.xcenter`, `.ycenter`, `.xbetween`, `.xright`, `.ytop`.
+   - Dimensions & Spacing: `.gap-*`, `.pad-*`, `.pad-x-*`, `.pad-y-*`, `.w-*`, `.h-*`.
+   - Visuals: `.surface`, `.raised`, `.border`, `.border-bottom`, `.radius-*`, `.shadow-*`.
+   - Typography: `.text-xs` .. `.text-5xl`, `.weight-500`, `.weight-600`, `.truncate`.
+   - Interactions: `.button`, `.primary`, `.ghost`, `.outline`, `.active`.
+4. **Hard Boundaries**:
+   - **NO in-component `<style>` blocks**: Components must remain pure markup and logic.
+   - **NO inline `style="..."` attributes**: Inline styles are unconstrained ad-hoc CSS.
+   - **NO raw hex colors (`#hex`)**: Every color must resolve through semantic tokens (`var(--bg)`, `var(--text-primary)`, `var(--border)`, etc.).
+   - **NO arbitrary pixel dimensions (>2px)**: Literal pixels bypass the dimension ladder. Only 1-2px (borders, hairlines) may be literal.
+   - **NO child combinators**: Selectors are plain descendants (`> *` is forbidden).
+5. **Mandatory Verification**:
+   Before claiming task completion, always execute:
+   ```bash
+   pnpm lint
+   pnpm check
+   ```
+   Both checks must pass with 0 errors.
+
+## Progressive Discovery Index
+
+| Styling Task | File to Inspect | Responsibility |
+|:---|:---|:---|
+| Active files and cascade order | `src/lib/styles/index.sass` | Master composition contract. |
+| Colors, semantic tokens, dark mode | `src/lib/styles/_00_tokens.sass` | Design token source of truth. |
+| Global resets and typography defaults | `src/lib/styles/_01_base.sass` | Low-specificity element defaults. |
+| Spacing, gaps, padding, dimensions | `src/lib/styles/_02_dimensions.sass` | L1 spacing & dimension ladders. |
+| Text sizes, roles, weights, tracking | `src/lib/styles/_03_typography.sass` | L5 typography primitives, roles, and modifiers. |
+| Flex/grid containers & axis alignment | `src/lib/styles/_04_containers.sass` | L2 structural layout containers. |
+| Macro grid layouts & responsive columns | `src/lib/styles/_05_layouts.sass` | L3 column stepping (.grid-1..12). |
+| Page frames, headers, sidebars, rails | `src/lib/styles/_06_shells.sass` | L4 application shell hierarchy. |
+| Buttons, links, pills, states | `src/lib/styles/_07_interactions.sass` | L5 orthogonal interactive axes. |
+| Backgrounds, ink, shadows, borders | `src/lib/styles/_08_visuals.sass` | L5 surface styling & decorative treatments. |
+| Project-specific third-party overrides | `src/lib/styles/_09_own.sass` | Sanctioned extension point. |
+
+## Handling Coverage Gaps
+
+If a visual requirement cannot be expressed with existing canonical classes:
+1. Do NOT write an ad-hoc inline style or component `<style>` block.
+2. Check if an existing token in `_00_tokens.sass` can be composed.
+3. If genuine new utility or shell class is required, add it to the designated layer partial in `src/lib/styles` with a trailing `// description` comment and run `pnpm registry`.
+4. If it is a project-specific extension, declare it in `_09_own.sass`.