@iyulab/components 1.22.0 → 1.24.0

package/skills/iyulab-components/references/usage.md

@@ -64,13 +64,84 @@ const current = Theme.get(); // 'system' | 'light' | 'dark' | undefined
 
 ### Brand color customization
 
+**Recommended — derive the whole ramp from one seed:**
+
+```ts
+import { Theme } from '@iyulab/components';
+
+Theme.accent('#7c3aed');   // computes --u-primary-color-{weakest,weaker,weak,…,strong} + txt
+Theme.accent(null);        // back to the sheet defaults
+```
+
+The computed ramp satisfies the contrast contract this library tests against — text on the
+accent surface ≥ 4.5:1, accent text on the page background ≥ 4.5:1, `-strong` distinguishable
+from `-color`, and `-weak` usable as a non-text graphic (≥ 3:1). It is **recalculated when the
+theme changes**, because those targets are relative to the page background.
+
+#### How many tokens does the `primary` role have? **Seven.**
+
+`Theme.accent()` sets **six** of them:
+
+| Token | `Theme.accent()` | What reads it |
+|---|---|---|
+| `--u-primary-color` | ✅ | accent surface — 21 source files |
+| `--u-primary-color-strong` | ✅ | text/icons on the page background; hover · active · link · focus ring — 14 files |
+| `--u-primary-color-weak` | ✅ | non-text graphics |
+| `--u-primary-color-weaker` | ✅ | decorative |
+| `--u-primary-color-weakest` | ✅ | decorative |
+| `--u-primary-txt-color` | ✅ | text on the accent surface |
+| **`--u-primary-bg-color`** | 🔴**no** | tinted **surface behind text** — `u-tag`'s `--tag-hue-surface` |
+
+🔴 **`Theme.accent()` does not touch `--u-primary-bg-color`.** It stays on the sheet default
+(a blue tint), so a seeded brand leaves tinted surfaces blue. Set it yourself alongside the seed:
+
+```ts
+Theme.accent('#7c3aed');
+document.documentElement.style.setProperty('--u-primary-bg-color', '#f3e8ff');
+```
+
+Pick a tint that keeps your body text readable on it — the built-in sheet values sit at roughly
+1.14:1 (light) and 1.03:1 (dark) against the page background. Deriving this step automatically is
+tracked as open work, because the sheet pairs it by hand across five colour roles and two themes.
+
+**Manual override** — you must set the steps you use, not just one:
+
 ```css
 :root {
-  --u-primary-color: #7c3aed;
+  --u-primary-color-weak: #a78bfa;    /* graphics on the page background */
+  --u-primary-color: #7c3aed;         /* accent surface */
+  --u-primary-color-strong: #5b21b6;  /* text/icons on the page background */
+  --u-primary-txt-color: #ffffff;     /* text on the accent surface */
+  --u-primary-bg-color: #f3e8ff;      /* tinted surface behind text */
 }
 ```
 
-Interactive components derive hover/active/surface/outline styles from this token.
+⚠ Setting `--u-primary-color` alone is **not enough**: hover/focus/link colors resolve from
+`--u-primary-color-strong`, so they stay on the default ramp and your brand looks half-applied.
+The measured symptom is a *selected table row* or *tag* that stays blue while buttons turn brand —
+that one is `--u-primary-bg-color`.
+
+### Typography
+
+The sheet defines seven semantic steps — `display`, `title`, `subtitle`, `body`, `label`,
+`caption`, `overline` — each with `-size`, `-weight`, `-leading`, `-tracking`. Use them from
+markup with [`u-text`](./components/text.md) instead of writing your own CSS:
+
+```html
+<u-text level="1" variant="display">Document title</u-text>
+<u-text variant="subtitle" tone="weak">One-line description</u-text>
+<u-text>Body copy</u-text>
+<u-text variant="caption" tone="weak">Helper text</u-text>
+```
+
+`variant` is the visual step and `level` is the document level — they are independent, and
+`level` renders a real `<h1>`–`<h6>` so the heading is read as one.
+
+To rebrand typography, override the tokens rather than the screens:
+
+```css
+:root { --u-text-title-size: 22px; --u-text-title-weight: 800; }
+```
 
 ---
 

package/skills/iyulab-components/references/utilities/theme.md

@@ -22,17 +22,34 @@ await Theme.init({
 });
 ```
 
-## Primary Color Customization
+## Brand accent
 
-Interactive components derive their accent palette from `--u-primary-color`.
+**Recommended — derive the whole ramp from one seed:**
+
+```ts
+Theme.accent('#7c3aed');   // computes --u-primary-color-{weakest…strong} + --u-primary-txt-color
+Theme.accent(null);        // back to the sheet defaults
+```
+
+The computed ramp satisfies the contrast contract this library tests against — text on the accent
+surface ≥ 4.5:1, accent text on the page background ≥ 4.5:1, `-strong` distinguishable from
+`-color`, and `-weak` usable as a non-text graphic (≥ 3:1). It is **recalculated when the theme
+changes**, because those targets are relative to the page background.
+
+**Manual override** — set the steps you use, not just one:
 
 ```css
 :root {
-  --u-primary-color: #7c3aed; /* global brand/accent color */
+  --u-primary-color-weak: #a78bfa;    /* graphics on the page background */
+  --u-primary-color: #7c3aed;         /* accent surface */
+  --u-primary-color-strong: #5b21b6;  /* text/icons on the page background */
+  --u-primary-txt-color: #ffffff;     /* text on the accent surface */
 }
 ```
 
-With this single token override, components such as buttons, checkbox/radio/switch, tab-panel, badge, and tag recalculate hover/active/surface/outline colors automatically.
+> ⚠ Overriding `--u-primary-color` **alone is not enough**. Hover, focus and link colors resolve
+> from `--u-primary-color-strong`, so they stay on the default ramp and the brand looks
+> half-applied. (The sheet derives no step from `--u-primary-color` — measured: 0 references.)
 
 ## API
 
@@ -41,6 +58,8 @@ With this single token override, components such as buttons, checkbox/radio/swit
 | `Theme.init(options?)` | `Promise<void>` | Initialize and apply theme |
 | `Theme.get()` | `ThemeType \| undefined` | Get current theme |
 | `Theme.set(theme)` | `void` | Set theme (`'light'`, `'dark'`, `'system'`) |
+| `Theme.resolved()` | `'light' | 'dark'` | The theme actually applied — use this, not `get()`, for brightness branches |
+| `Theme.accent(seed)` | `void` | Derive the `--u-primary-*` ramp from a brand color; `null` clears it |
 | `Theme.isInitialized` | `boolean` | Whether `init()` has been called |
 
 ## Types