@tenphi/tasty 0.0.0-snapshot.d2dcdeb → 0.0.0-snapshot.d4ccea8

package/docs/debug.md

@@ -12,6 +12,8 @@ In development mode (`isDevEnv()` returns `true`), `tastyDebug` is automatically
 
 All methods **log to the console by default**. Pass `{ raw: true }` to suppress logging and only return data.
 
+> **Note (2.0.0+):** Class names use a content-addressed base36 hash format (e.g. `t3a5f`) instead of the previous sequential `t{number}` format. Cross-environment hydration reads the rendered class list from `window.__TASTY__` (the legacy `window.__TASTY_SSR_CACHE__` global was removed in 2.0.0).
+
 ---
 
 ## Quick Start
@@ -66,18 +68,18 @@ Retrieves CSS text for a given target. Logs the result with rule count and size.
 |---|---|
 | `'all'` | All tasty CSS (component + global + raw) |
 | `'active'` | CSS for classes currently in the DOM |
-| `'unused'` | CSS with refCount = 0 (cached but not used) |
+| `'unused'` | CSS for injected classes no element carries (cached but not rendered) |
 | `'global'` | Only global CSS (from `injectGlobal`) |
 | `'page'` | All CSS on the page (including non-tasty) |
-| `'t42'` | CSS for a specific tasty class |
-| `['t0', 't5']` | CSS for multiple tasty classes |
+| `'t3a5f'` | CSS for a specific tasty class (class names are `t` + base36 hash) |
+| `['t3a5f', 't9k2']` | CSS for multiple tasty classes |
 | `'.my-button'` | CSS affecting a DOM element (by selector) |
 | `element` | CSS affecting a DOM element (by reference) |
 
 **Extra options:**
 
 ```typescript
-interface CssOptions extends DebugOptions {
+interface CSSOptions extends DebugOptions {
   prettify?: boolean; // Format output (default: true)
   source?: boolean;   // Read original CSS instead of live CSSOM (default: false, dev-mode only)
 }
@@ -88,11 +90,11 @@ interface CssOptions extends DebugOptions {
 tastyDebug.css('active');
 
 // Specific class, silent
-const css = tastyDebug.css('t42', { raw: true });
+const css = tastyDebug.css('t3a5f', { raw: true });
 
 // Compare original vs browser-parsed CSS (dev mode only)
-tastyDebug.css('t42');                    // live CSSOM
-tastyDebug.css('t42', { source: true }); // original output
+tastyDebug.css('t3a5f');                    // live CSSOM
+tastyDebug.css('t3a5f', { source: true }); // original output
 
 // Shadow DOM
 tastyDebug.css('all', { root: shadowRoot });
@@ -109,14 +111,14 @@ Inspects a DOM element and returns detailed information about its tasty styles,
 ```typescript
 interface InspectResult {
   element?: Element | null;
-  classes: string[];    // Tasty classes on the element
-  chunks: ChunkInfo[];  // Chunk assignment per class
-  css: string;          // Prettified CSS
-  size: number;         // CSS size in characters
-  rules: number;        // Number of CSS rule blocks
+  classes: string[];          // Tasty classes on the element
+  chunks: DebugChunkInfo[];   // Chunk assignment per class
+  css: string;                // Prettified CSS
+  size: number;               // CSS size in characters
+  rules: number;              // Number of CSS rule blocks
 }
 
-interface ChunkInfo {
+interface DebugChunkInfo {
   className: string;
   chunkName: string | null; // e.g., 'appearance', 'font', 'dimension'
 }
@@ -125,11 +127,11 @@ interface ChunkInfo {
 ```typescript
 tastyDebug.inspect('.my-card');
 // Logs: inspect div — 3 classes, 5 rules, 1.2KB
-//       Chunks: t3→appearance, t7→font, t12→dimension
+//       Chunks: t3a5f→appearance, t9k2→font, tb71→dimension
 
 // Silent
 const result = tastyDebug.inspect('.my-card', { raw: true });
-console.log(result.classes);  // ['t3', 't7', 't12']
+console.log(result.classes);  // ['t3a5f', 't9k2', 'tb71']
 console.log(result.rules);    // 5
 ```
 
@@ -239,7 +241,9 @@ tastyDebug.cache();
 
 ### `cleanup(opts?): void`
 
-Forces immediate cleanup of all unused styles (those with `refCount = 0`).
+Removes every injected style that is neither carried by an element nor pinned by
+an outstanding `inject()` handle — the same set `summary()` reports as unused.
+Equivalent to `gc({ force: true })`.
 
 ```typescript
 tastyDebug.cleanup();
@@ -291,10 +295,10 @@ tastyDebug.summary({ root: shadowRoot });
 tastyDebug.inspect('.my-button');
 
 // 2. See CSS for a specific class
-tastyDebug.css('t3');
+tastyDebug.css('t3a5f');
 
 // 3. Compare original vs browser-parsed (dev mode)
-tastyDebug.css('t3', { source: true });
+tastyDebug.css('t3a5f', { source: true });
 ```
 
 ### Checking cache efficiency

package/docs/design-system.md

@@ -1,8 +1,8 @@
 # Building a Design System
 
-This guide walks through building a design-system styling layer on top of Tasty — defining tokens, state aliases, recipes, primitive components, and compound components with sub-elements.
+This guide shows how to build shared React components whose styles stay predictable as states, variants, themes, and responsive rules accumulate. You will define tokens, state aliases, recipes, primitive APIs, and compound components with sub-elements.
 
-It assumes you have already decided to adopt Tasty. The goal is not just to centralize tokens, but to define a styling language whose component states resolve deterministically across variants, responsive rules, and sub-elements. For evaluation criteria, audience fit, and incremental adoption phases, see the [Adoption Guide](adoption.md). For the recommended component patterns and mental model, see [Methodology](methodology.md).
+It assumes you have already decided to adopt Tasty. The goal is not only to centralize values, but to give your design system one state model and a governed component-facing styling API. For evaluation criteria and incremental rollout, see the [Adoption Guide](adoption.md). For the recommended component architecture, see [Methodology](methodology.md).
 
 ---
 
@@ -43,8 +43,8 @@ configure({
     '#border': '#e0e0e0',
 
     // Unit values
-    '$gap': '8px',
-    '$radius': '4px',
+    $gap: '8px',
+    $radius: '4px',
     '$border-width': '1px',
     '$outline-width': '2px',
   },
@@ -91,8 +91,18 @@ import { configure } from '@tenphi/tasty';
 
 configure({
   presets: {
-    h1: { fontSize: '2rem', lineHeight: '1.2', letterSpacing: '-0.02em', fontWeight: 700 },
-    t2: { fontSize: '0.875rem', lineHeight: '1.5', letterSpacing: 'normal', fontWeight: 400 },
+    h1: {
+      fontSize: '2rem',
+      lineHeight: '1.2',
+      letterSpacing: '-0.02em',
+      fontWeight: 700,
+    },
+    t2: {
+      fontSize: '0.875rem',
+      lineHeight: '1.5',
+      letterSpacing: 'normal',
+      fontWeight: 400,
+    },
   },
 });
 ```
@@ -117,14 +127,22 @@ Then use `preset: 'h1'` or `preset: 't2'` in any component's styles.
 
 ### Registering brand fonts
 
-Register your design system's custom fonts via `configure({ fontFace })` so every component can reference them:
+Register your design system's custom fonts via `configure({ fontFaces })` so every component can reference them:
 
 ```ts
 configure({
-  fontFace: {
+  fontFaces: {
     'Brand Sans': [
-      { src: 'url("/fonts/brand-regular.woff2") format("woff2")', fontWeight: 400, fontDisplay: 'swap' },
-      { src: 'url("/fonts/brand-bold.woff2") format("woff2")', fontWeight: 700, fontDisplay: 'swap' },
+      {
+        src: 'url("/fonts/brand-regular.woff2") format("woff2")',
+        fontWeight: 400,
+        fontDisplay: 'swap',
+      },
+      {
+        src: 'url("/fonts/brand-bold.woff2") format("woff2")',
+        fontWeight: 700,
+        fontDisplay: 'swap',
+      },
     ],
   },
 });
@@ -144,7 +162,8 @@ configure({
     '@mobile': '@media(w < 768px)',
     '@tablet': '@media(768px <= w < 1024px)',
     '@desktop': '@media(w >= 1024px)',
-    '@dark': '@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))',
+    '@dark':
+      '@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))',
     '@reduced-motion': '@media(prefers-reduced-motion: reduce)',
   },
 });
@@ -185,7 +204,7 @@ configure({
     'input-reset': {
       border: 'none',
       outline: 'none',
-      fill: 'transparent',
+      fill: '#clear',
       font: true,
       preset: 't3',
     },
@@ -211,7 +230,7 @@ const ProfileCard = tasty({
 });
 ```
 
-Use the `/` separator when a recipe should be applied *after* local styles (post-merge), so recipe states take priority:
+Use the `/` separator when a recipe should be applied _after_ local styles (post-merge), so recipe states take priority:
 
 ```tsx
 const Input = tasty({
@@ -283,12 +302,12 @@ Product engineers use these to compose layouts without writing CSS:
 
 Match the prop set to the component's role:
 
-| Component category | Recommended styleProps |
-|--------------------|----------------------|
-| Layout containers (`Space`, `Box`, `Grid`) | `FLOW_STYLES` — flow, gap, align, justify, padding, fill |
-| Positioned elements (`Button`, `Badge`) | `POSITION_STYLES` — placeSelf, gridArea, order |
-| Text elements | `['preset', 'color']` or a custom subset |
-| Compound components | Typically none — styling happens via sub-elements and wrapping |
+| Component category                         | Recommended styleProps                                         |
+| ------------------------------------------ | -------------------------------------------------------------- |
+| Layout containers (`Space`, `Box`, `Grid`) | `FLOW_STYLES` — flow, gap, align, justify, padding, fill       |
+| Positioned elements (`Button`, `Badge`)    | `POSITION_STYLES` — placeSelf, gridArea, order                 |
+| Text elements                              | `['preset', 'color']` or a custom subset                       |
+| Compound components                        | Typically none — styling happens via sub-elements and wrapping |
 
 Exposing too many props weakens the design system's constraints. See [Methodology — styleProps as the public API](methodology.md#styleprops-as-the-public-api) for the rationale.
 
@@ -335,9 +354,7 @@ Usage:
 ```tsx
 <Card>
   <Card.Title>Monthly Revenue</Card.Title>
-  <Card.Content>
-    $1.2M — up 12% from last month.
-  </Card.Content>
+  <Card.Content>$1.2M — up 12% from last month.</Card.Content>
   <Card.Footer>
     <Button>Details</Button>
   </Card.Footer>
@@ -365,13 +382,15 @@ A design system works best when the rules for customization are explicit. Tasty
 2. **Use modProps** — control component states through typed props instead of `mods`:
 
 ```tsx
-<Button isLoading size="large">Submit</Button>
+<Button isLoading size="large">
+  Submit
+</Button>
 ```
 
 3. **Pass tokens** — inject runtime values through the `tokens` prop for per-instance customization:
 
 ```tsx
-<ProgressBar tokens={{ '$progress': `${percent}%` }} />
+<ProgressBar tokens={{ $progress: `${percent}%` }} />
 ```
 
 4. **Create styled wrappers** — extend a component's styles with `tasty(Base, { styles })`: