first-commit

craft/color.md

@@ -0,0 +1,88 @@
+# Color craft rules
+
+Universal color rules applied on top of the active `DESIGN.md`. The
+design system supplies the palette tokens; this file enforces how to
+*use* them.
+
+> Adapted from [refero_skill](https://github.com/referodesign/refero_skill)
+> (MIT). All examples reference Open Design's standard tokens
+> (`--bg`, `--surface`, `--fg`, `--muted`, `--border`, `--accent`).
+
+## Palette structure
+
+A coherent palette has four layers. Plan all four before writing any CSS.
+
+| Layer | Share of pixels | Tokens |
+|---|---|---|
+| **Neutrals** | 70–90% | `--bg`, `--surface`, `--fg`, `--muted`, `--border` |
+| **Accent** (one) | 5–10% | `--accent` only — never invent a second accent |
+| **Semantic** | 0–5% | `--success`, `--warn`, `--danger` |
+| **Effect** | <1% | gradients, glows; rarely justified |
+
+## Accent discipline
+
+The single biggest readability failure in AI-generated UIs is accent
+overuse. Hard caps:
+
+- **At most 2 visible uses of `--accent` per screen.** Typical pair:
+  one eyebrow / chip + one primary CTA. Or one accent card + one tab
+  pill. Pick a pair, not a flood.
+- Links count as accent; demote to `--fg` underline if you also have a
+  CTA on the same screen.
+- Hover/focus rings count as accent. Ration accordingly.
+
+## Contrast minimums
+
+Run these as gates, not goals:
+
+| Pair | Minimum |
+|---|---|
+| Body text (≤16 px) on background | **4.5:1** |
+| Large text (>18 px or 14 px bold) | **3:1** |
+| UI components against adjacent surfaces | **3:1** |
+
+When the brand color clashes (low-contrast indigo on light background is
+common), darken the accent to a `600`-level shade for text use; reserve
+the brand-bright variant for fills only.
+
+## Dark themes
+
+Avoid pure black and pure white — both cause vibration and eye strain.
+
+| Token | Dark theme | Light theme |
+|---|---|---|
+| Background | `#0f0f0f` (not `#000`) | `#fafafa` (not `#fff`) |
+| Foreground | `#f0f0f0` (not `#fff`) | `#111111` (not `#000`) |
+
+On dark surfaces, prefer **semi-transparent white borders** over solid
+dark borders — a 1px `rgba(255,255,255,0.08)` reads as structure
+without adding visual noise.
+
+## Semantic color naming
+
+Always name tokens by **purpose**, never by hue:
+
+```css
+/* good */
+--accent: #2f6feb;
+--success: #17a34a;
+
+/* bad — locks you out of theming */
+--blue-500: #2f6feb;
+--green-500: #17a34a;
+```
+
+## Anti-defaults
+
+- **Indigo `#6366f1`** (Tailwind `indigo-500`) is the most reliable
+  AI-slop tell. The active `DESIGN.md` provides `--accent`; use it. If
+  the brief truly needs indigo, make the user say so explicitly. If
+  your `DESIGN.md` encodes indigo as `--accent`, that is intentional —
+  the linter only flags hardcoded hex, so `var(--accent)` uses are
+  unaffected even when the resolved color happens to be `#6366f1`.
+- **Two-stop "trust" gradient** (purple → blue, blue → cyan, etc.) on a
+  hero is the second most reliable tell. A flat surface + one
+  type-driven hierarchy beats it every time.
+- **Decorative gradients with no functional purpose**. Gradients should
+  separate hierarchies (header → body, primary CTA → secondary), not
+  decorate empty space.