@w3kits-com/plugin-opendesign 0.1.8 → 0.1.10

package/dist/__w3kits/assets/design-systems/kami/DESIGN.md

@@ -0,0 +1,410 @@
+# Design System Inspired by kami (紙 / 纸)
+
+> Category: Editorial & Print
+> Editorial paper system: warm parchment canvas, ink-blue accent, serif-led hierarchy. Built for resumes, one-pagers, white papers, portfolios, slide decks — anything that should feel like high-quality print rather than UI. Multilingual by design (EN · zh-CN · ja).
+
+## 1. Visual Theme & Atmosphere
+
+kami compresses into one sentence: **warm parchment canvas, ink-blue accent, serif carries hierarchy, no cool grays, no hard shadows.** It is not a UI framework — it is a constraint system for the page, designed to keep deliverables stable, clear, and unmistakably *printed*. The name reads as **kami / 紙 / 纸** — the same word for "paper" across Japanese and Chinese — and the system is co-designed across English, Simplified Chinese, and Japanese typesetting from the ground up, not retrofitted.
+
+The page background is parchment (`#f5f4ed`), never pure white. Text sits on cream. The single chromatic move is ink-blue (`#1B365D`) — used on section numbers, primary CTAs, the left rule of a quote, the W500 weight in a metric. Everything else is a warm neutral with a yellow-brown undertone; cool blue-grays are absent on purpose.
+
+Hierarchy is carried almost entirely by **serif type at a single weight (500)**. There is no bold, no italic, no second accent color. Density is achieved through tight line-heights (1.10–1.55), four-level gray ramps, and ring/whisper shadows that act as halos rather than drops. The aesthetic borrows from editorial print, technical white papers, and old typewritten correspondence — the goal is "good content on good paper," not "modern app UI."
+
+**Key Characteristics:**
+- Warm parchment canvas (`#f5f4ed`) — never `#ffffff`
+- Single accent: ink-blue (`#1B365D`), covers ≤ 5% of any surface
+- All grays warm (R ≈ G > B), no cool blue-grays anywhere
+- Serif everywhere for hierarchy: Charter (EN), TsangerJinKai02 / Source Han Serif (CN), YuMincho (JA)
+- Locked at weight 500 — no synthetic bold (700/900) and **no italic**
+- Tight print rhythm (line-heights 1.10–1.55), much denser than typical web body
+- Depth via 1px rings and whisper shadows (`0 4px 24px rgba(0,0,0,0.05)`), never hard drop shadows
+- Tag fills are solid hex (e.g. `#E4ECF5`), never `rgba()` — print renderers double-paint alpha tags
+- Numbers sit in `font-variant-numeric: tabular-nums` so columns of metrics don't shimmy
+
+## 2. Color Palette & Roles
+
+### Brand
+- **Ink Blue** (`#1B365D`): The only chromatic color. CTAs, section numbers, link text on light surfaces, the left rule on a section title or quote, the active state of a switcher, the W500 metric value.
+- **Ink Light** (`#2D5A8A`): Brighter variant, only for links sitting on dark surfaces.
+
+> Rule: ink-blue covers ≤ **5% of document surface area**. More than that turns into ornament and the restraint collapses.
+
+### Surface
+- **Parchment** (`#f5f4ed`): The page background — warm cream, the emotional foundation. Never replace with white.
+- **Ivory** (`#faf9f5`): Cards and lifted containers. Sits one half-shade brighter than parchment.
+- **Warm Sand** (`#e8e6dc`): Default button background, secondary interactive surfaces.
+- **Dark Surface** (`#30302e`): Dark-theme containers — warm charcoal, not slate.
+- **Deep Dark** (`#141413`): Dark-theme page background. Olive-tinted near-black, never `#000000`.
+
+### Text (four levels — no fifth)
+- **Near Black** (`#141413`): Primary text. Slight olive warmth, gentler than pure black.
+- **Dark Warm** (`#3d3d3a`): Secondary text, table headers, link defaults.
+- **Olive** (`#504e49`): Subtext, captions, descriptions. (JA override: `#4d4c48` because YuMincho strokes are thinner.)
+- **Stone** (`#6b6a64`): Tertiary — dates, metadata, meta labels.
+
+### Border
+- **Border** (`#e8e6dc`): Primary border — section dividers, card edges, table headers.
+- **Border Soft** (`#e5e3d8`): Row separators, inner dividers, subtle internal lines.
+
+### Tag tints (solid, NOT rgba)
+Print renderers (WeasyPrint and friends) double-paint alpha fills, leaving a visible "double rectangle" on zoom. Tag and chip backgrounds must be solid hex, pre-blended over parchment:
+
+| Effective alpha of `#1B365D` over parchment | Solid hex |
+|---|---|
+| 0.08 | `#EEF2F7` |
+| 0.14 | `#E4ECF5` |
+| **0.18 (default tag)** | **`#E4ECF5`** |
+| 0.22 | `#D0DCE9` |
+| 0.30 | `#D6E1EE` |
+
+### Gradient System
+kami is **gradient-free** by default. The only sanctioned gradient is the soft tag brush running `#D6E1EE → #E4ECF5 → #EEF2F7` left-to-right at very low contrast — used at most once per page on a single decorative tag. Do not introduce hero gradients, brand-color washes, or backdrop-filter blurs.
+
+### Forbidden colors
+- `#ffffff` as a page background
+- `#000000` anywhere
+- Any cool-gray surface (`#f8f9fa`, `#f3f4f6`, `slate-*`)
+- Any second saturated color (no second accent — pick ink-blue or pick nothing)
+
+## 3. Typography Rules
+
+### Font Stacks
+
+```css
+/* English (default) */
+--serif: Charter, Georgia, Palatino, "Times New Roman", serif;
+
+/* Chinese */
+--serif: "TsangerJinKai02", "Source Han Serif SC", "Noto Serif CJK SC",
+         "Songti SC", "STSong", Georgia, serif;
+
+/* Japanese */
+--serif: "YuMincho", "Yu Mincho", "Hiragino Mincho ProN",
+         "Noto Serif CJK JP", "Source Han Serif JP",
+         "TsangerJinKai02", Georgia, serif;
+
+/* Mono — must include CJK fallback so labels/comments don't render as boxes */
+--mono: "JetBrains Mono", "SF Mono", "Fira Code", Consolas, Monaco,
+        "TsangerJinKai02", "Source Han Serif SC", monospace;
+
+/* Sans always equals serif. There is no separate sans-serif family. */
+--sans: var(--serif);
+```
+
+### When to swap the stack
+
+The three stacks above are **alternative values for `--serif`**, not three families layered together. When generating an artifact, set the primary stack on `:root` based on the dominant language of the content; let the browser's per-glyph fallback resolve mixed-script text inline. Concretely:
+
+- `<html lang="en">` (or English-dominant content) → leave `--serif` on the EN stack. CJK glyphs that appear inline will fall through to the system Han fallback.
+- `<html lang="zh-CN">` → override `--serif` to the CN stack on `:root` or on `html[lang="zh-CN"]`. Latin glyphs render via the Georgia tail of the stack.
+- `<html lang="ja">` → override `--serif` to the JA stack and apply the `--olive: #4d4c48` text-color override (YuMincho strokes are thinner; the standard olive looks anemic against parchment).
+- Multi-language artifacts (e.g. a deck with one Japanese chapter): set the dominant-language stack on `:root`, then scope the override on a wrapper element (`section[lang="ja"] { --serif: …; }`). Do **not** chain all three families inside a single `font-family` — that dilutes the visual character of every page.
+
+### Hierarchy (screen, px)
+
+The hierarchy table below is sized for **screen-rendered web pages** (resume, one-pager, portfolio shown at desktop width). For other surfaces, scale from the print pt baseline using these ratios — the same rules the kami `slides.py` template applies:
+
+| Surface | Macro tokens (font, padding) | Micro tokens (border, radius, tracking) |
+|---|---|---|
+| Page / web artifact (one-pager, resume, white paper) | print pt × ~1.33 | print pt × 1 |
+| Slide / 1920×1080 deck | print pt × ~1.6 | print pt × ~0.6 |
+
+Concretely: a 22pt H1 in print becomes ~29px on a web page and ~36px on a slide; an 8pt letter-spacing value that reads as confident in print drops to ~5px on a slide. Letter-spacing always uses the slide micro ratio — print tracking applied at slide scale falls apart.
+
+| Role | Family | Size | Weight | Line-height | Letter-spacing | Notes |
+|------|--------|------|--------|-------------|----------------|-------|
+| Hero / Display | serif | 96–106px | 500 | 1.05–1.10 | -1.2px | One per page max — cover or one-pager hero |
+| Display CN/JA | serif | 48–64px | 500 | 1.10–1.12 | 0–0.3px | CJK glyphs need looser tracking and smaller absolute size |
+| Section title | serif | 28–32px | 500 | 1.20 | 0.4px | Anchors a chapter; preceded by section number |
+| H2 | serif | 22px | 500 | 1.25 | 0 | Subsection |
+| H3 | serif | 17–18px | 500 | 1.30 | 0 | Item title, card heading |
+| Manifesto / pull quote | serif | 20px | 400 | 1.65 | 0.05em | The one place letter-spacing earns its keep |
+| Lede | serif | 15–16px | 500 | 1.55 | 0 | Intro paragraph under a section title |
+| Body | serif | 14px | 400 | 1.55 | 0 (EN) · 0.35px (CN) · 0.02em (JA) | Reading body |
+| Body dense | serif | 13–14px | 400 | 1.40–1.45 | 0 | Resume, one-pager, dense lists |
+| Caption | serif | 12px | 500 | 1.45 | 0 | Notes, figure captions |
+| Eyebrow / overline | sans | 12px | 500 | 1 | 1.2px, **uppercase** | Section eyebrow, switcher, meta header |
+| Label | sans | 12px | 500 | 1.35 | 0.4px, uppercase | Small inline label, ink-blue if active |
+| Mono / spec | mono | 12–13px | 400 | 1.55 | 0.4px | Hex codes, type specs, code |
+
+### Weight rules
+- Serif uses **only weights 400 and 500**. No 600, no 700, no 900.
+- `strong { font-weight: 500 }` is explicitly set so browsers don't synthesize bold.
+- Sans labels may use 500 or 600 at small sizes for legibility.
+- **No italic anywhere.** No `font-style: italic`. If emphasis is needed, switch the color to ink-blue or wrap in a tag.
+
+### Line-height
+- Tight headline: 1.10–1.30 (display, H1, H2)
+- Dense body: 1.40–1.45 (resume, one-pager, dense lists)
+- Reading body: 1.50–1.55 (long-form chapters, letters)
+- Label / caption: 1.30–1.40
+
+Forbidden: 1.6+ (web rhythm, floats off the page) and 1.0–1.05 (lines collide except at giant display sizes).
+
+### Letter-spacing
+- EN body: `0`
+- CN body (TsangerJinKai02): `0.35px` to compensate for the font's natural density
+- JA body: `0.02em`
+- All-caps overlines and small labels (< 10pt): +0.5 to +1.2px is mandatory
+- Display CJK at 24px+: `0.2–1px` of optical breathing room
+- On slides, tracking is roughly **half** of print values — 8px tracking that reads as confident in a printed deck disintegrates at slide scale.
+
+### Tabular-nums contexts
+
+`font-variant-numeric: tabular-nums` is mandatory anywhere kami numbers stack vertically or sit alongside other numbers — uneven proportional digits read as a layout bug at print resolution. Apply it to:
+
+- Metric values (the big ink-blue number in `.metric-value`) and any side-by-side metric row
+- Slide footers and slide counters (`02 / 05`), page numbers, deck pagination
+- Section numbers in chapter heads (`01`, `02`, …) when they appear in a stacked TOC
+- Resume dates, employment ranges, and education years
+- Financial figures: revenue, ARR/MRR, valuations, tables of P&L line items
+- White-paper and equity-report data tables (every numeric column)
+- Stat-dashboard hero numbers and KPI grids
+- Changelog version numbers (`1.4.2 → 1.4.3`) and any inline release dates
+- Any inline numeric span inside a paragraph that compares values (`from 142 to 168`)
+
+Do **not** apply tabular-nums to running prose where a single number appears mid-sentence — proportional digits read better there. The rule is "stacks and tables, yes; sentences, no."
+
+## 4. Component Stylings
+
+### Cards / Containers
+```css
+background: var(--ivory);             /* never parchment — cards lift one shade */
+border: 1px solid var(--border);
+border-radius: 8px;                   /* default; featured cards 12px; hero 16–24px */
+padding: 28px 28px 24px;              /* component interior */
+transition: box-shadow 0.2s;
+/* Hover lifts via whisper shadow only — no transform, no brightness shift */
+&:hover { box-shadow: 0 4px 24px rgba(0,0,0,0.05); }
+```
+
+### Buttons
+```css
+.btn-primary {
+  background: var(--brand);                    /* #1B365D */
+  color: var(--ivory);
+  box-shadow: 0 0 0 1px var(--brand);          /* ring shadow as edge */
+  padding: 8px 14px;
+  border-radius: 8px;
+  font: 500 12px/1 var(--sans);
+  letter-spacing: 0.4px;
+}
+.btn-secondary {
+  background: var(--warm-sand);
+  color: var(--dark-warm);
+  box-shadow: 0 0 0 1px var(--border);
+}
+.btn-ghost {
+  background: transparent;
+  color: var(--brand);
+  box-shadow: 0 0 0 1px var(--brand);
+}
+```
+
+### Tags / Chips
+```css
+.tag {
+  font: 500 12px/1 var(--sans);
+  padding: 2px 7px;
+  border-radius: 2px;
+  color: var(--brand);
+  background: #EEF2F7;        /* solid hex, NOT rgba */
+  letter-spacing: 0.4px;
+}
+.tag.standard { background: #E4ECF5; padding: 2px 8px; border-radius: 4px; }
+
+/* The single sanctioned gradient — see §2 "Gradient System".
+ * Use at most once per page on a "featured" or "new" tag. The gradient
+ * runs darkest-to-lightest left-to-right so the eye reads it as a
+ * watercolor wash, not a button highlight. */
+.tag.brush {
+  background: linear-gradient(to right, #D6E1EE, #E4ECF5 70%, #EEF2F7);
+}
+```
+
+```html
+<!-- Example: a single brush tag flagging the new chapter in a long doc -->
+<span class="tag brush">New · Edition 02</span>
+```
+
+### Quote
+```css
+.quote {
+  border-left: 2px solid var(--brand);
+  padding: 4px 0 4px 14px;
+  font: 500 15px/1.55 var(--serif);
+  color: var(--olive);
+}
+```
+
+### Section title pattern
+```html
+<div class="section-head">
+  <p class="section-num">01</p>            <!-- ink-blue, 14px serif, tracking 0.4px -->
+  <h2 class="section-title">Color</h2>     <!-- 32px serif 500 -->
+  <p class="section-lede">Optional one-line description in olive.</p>
+</div>
+```
+The number is set in the same serif as the title, in ink-blue, the same size as caption text. There is no underline, no left bar, no eyebrow — the number *is* the marker.
+
+### Metrics
+```html
+<div class="metric">
+  <div class="metric-value">8.4×</div>     <!-- serif 500 24px ink-blue, tabular-nums -->
+  <div class="metric-label">faster ship</div> <!-- serif 12px olive -->
+</div>
+```
+Numbers always sit in `font-variant-numeric: tabular-nums` so adjacent metrics align.
+
+### Lists
+```css
+ul.dash {
+  list-style: none; padding: 0;
+}
+ul.dash li {
+  position: relative; padding-left: 14px;
+}
+ul.dash li::before {
+  content: "\2013";          /* en-dash, ink-blue */
+  position: absolute; left: 0;
+  color: var(--brand);
+}
+```
+Bullets are en-dashes in ink-blue, never filled discs.
+
+### Code block
+```css
+.code {
+  background: var(--ivory);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 12px 14px;
+  font: 12px/1.55 var(--mono);
+  color: var(--near-black);
+  white-space: pre;
+}
+.code .k { color: var(--brand); }   /* keyword */
+.code .c { color: var(--stone); }   /* comment */
+```
+
+## 5. Layout Principles
+
+### Page geometry (print A4)
+
+| Document | Top | Right | Bottom | Left |
+|---|---|---|---|---|
+| Resume (dense) | 11mm | 13mm | 11mm | 13mm |
+| One-Pager | 15mm | 18mm | 15mm | 18mm |
+| Long Doc | 20mm | 22mm | 22mm | 22mm |
+| Letter | 25mm | 25mm | 25mm | 25mm |
+| Portfolio | 12mm | 15mm | 12mm | 15mm |
+
+Rule: **denser = smaller margins, more formal = larger margins.**
+
+### Web / screen pages
+- Max content width: `1120px`, centered, with `padding: 88px 64px 120px` on desktop.
+- Section gap: `72px` between top-level sections.
+- Card-grid columns: 2 by default at desktop; collapse to 1 below 768px.
+- Table columns sized in absolute px (not %), so kami tables don't reflow into spaghetti.
+
+### Slides (1920×1080)
+- Four-side padding baseline: `--slide-pad: 80px`.
+- Padding-top of a content slide: 72–80px (print is 96–120px; slides are more compact).
+- Sizing follows the surface ratios from §3 ("Hierarchy"): macro tokens × 1.6, micro tokens × 0.6 against the print pt baseline.
+- Cover and chapter slides may flip background to ink-blue (`#1B365D`) with ivory text; everything else stays on parchment.
+
+## 6. Depth & Elevation
+
+Three sanctioned levels — that is the entire system:
+
+| Level | Treatment | Use |
+|-------|-----------|-----|
+| Flat (0) | No shadow, no border | Body text, manifesto, paragraphs on parchment |
+| Ring (1) | `1px solid var(--border)` or `0 0 0 1px var(--brand)` | Cards, primary buttons, table edges |
+| Whisper (2) | `0 4px 24px rgba(0,0,0,0.05)` | Hovered cards, lifted hero containers, screenshots |
+
+Forbidden:
+- Hard drop shadows (`0 12px 40px rgba(0,0,0,0.25)` and the like) — the page is paper, not a UI panel
+- Neumorphism, glassmorphism, backdrop-filter blurs
+- Multi-layer composite shadows
+
+### Border radius scale
+`2px → 4px → 6px → 8px (default) → 12px → 16px`. Tags hover at 2–4px, buttons and cards at 8px, featured / hero containers at 12–16px. Anything above 16px is reserved for cover-slide visuals.
+
+## 7. Do's and Don'ts
+
+### Do
+- Use parchment (`#f5f4ed`) as the page background — the warm cream tone *is* the kami personality.
+- Use a single serif weight (500) for every heading; let size carry hierarchy.
+- Use ink-blue (`#1B365D`) only for primary CTAs, section numbers, links, the left rule of a quote, and the W500 in metrics.
+- Keep every gray warm (yellow-brown undertone). When in doubt, sample with `R ≈ G > B`.
+- Use ring shadows or whisper shadows for elevation; never hard drops.
+- Set tag backgrounds as solid hex pre-blended over parchment, never `rgba()`.
+- Set numbers in `font-variant-numeric: tabular-nums`.
+- Pair the section number with the section title in the same serif — no eyebrow needed.
+- Default bullets to ink-blue en-dashes (`–`).
+
+### Don't
+- Don't use `#ffffff` as page background, anywhere.
+- Don't introduce a second accent color or a chromatic gradient.
+- Don't use cool blue-grays (`slate-*`, `#f3f4f6`, `#6b7280`). Every neutral is warm.
+- Don't use bold (700+) on serif — weight 500 is the ceiling.
+- **Don't use italic anywhere.** No `font-style: italic`. Swap to ink-blue or a tag instead.
+- Don't use sans-serif for headlines or body — sans is reserved for eyebrows, switchers, and small labels (and the sans stack literally equals the serif stack).
+- Don't drop body line-height below 1.4 or push it above 1.55 — that range *is* kami's reading rhythm.
+- Don't use round-disc bullets, drop shadows, or pill-shaped chips with heavy borders.
+- Don't apply `backdrop-filter`, `mix-blend-mode`, or any modern compositing trick — the system targets print fidelity.
+
+## 8. Responsive Behavior
+
+### Breakpoints
+
+| Name | Width | Key Changes |
+|------|-------|-------------|
+| Phone | < 768px | Single column. Hero 46px, section title 24px, manifesto 17px. Card padding drops to 20px 16px. Hide `.hero-tokens` row. |
+| Tablet | 768–979px | Most 2-col grids hold; switch tag tints from 5 to 3 columns. |
+| Desktop | ≥ 980px | Full 2-col / 4-col grids, JA gets `white-space: nowrap` rescue rules on long ledes. |
+
+### Touch targets
+- Buttons keep `8 14px` padding minimum.
+- Tap targets stay above 44×44 by giving cards generous internal padding rather than oversizing chrome.
+
+### Print
+- `@page { size: A4; margin: 14mm 16mm; background: #f5f4ed; }`.
+- Section, hero, family, comp, swatch, tint, quote, blockquote, pre, tr, anti-pattern blocks all use `break-inside: avoid` so kami pages don't snap mid-card.
+- `-webkit-print-color-adjust: exact` is required so the parchment background actually reaches paper.
+
+## 9. Agent Prompt Guide
+
+### Quick Color Reference
+- Page Background: "Parchment (#f5f4ed)"
+- Card Surface: "Ivory (#faf9f5)"
+- Brand / CTA: "Ink Blue (#1B365D)"
+- Primary Text: "Near Black (#141413)"
+- Secondary Text: "Dark Warm (#3d3d3a)"
+- Subtext / Caption: "Olive (#504e49)"
+- Tertiary / Meta: "Stone (#6b6a64)"
+- Border: "Border (#e8e6dc)"
+- Tag fill (default): "#E4ECF5 solid (NOT rgba)"
+
+### Example Component Prompts
+- "Build a kami one-pager hero on Parchment (#f5f4ed). Eyebrow row in 12px sans uppercase Stone (#6b6a64), letter-spacing 1.2px. Headline in serif 500 at 96px Near Black (#141413), line-height 1.05, letter-spacing -1.2px. Tagline below in serif 500 at 21px Olive (#504e49)."
+- "Design a kami section header. A two-line stack: section number `01` in serif 500 at 14px Ink Blue (#1B365D) tracking 0.4px, then the title in serif 500 at 32px Near Black. Optional lede in serif 500 at 16px Olive."
+- "Render a kami metric row of three metrics. Each metric is a vertical pair: value in serif 500 at 24px Ink Blue with `font-variant-numeric: tabular-nums`, label in 12px Olive. Gap between metrics: 28px."
+- "Build a kami card on Ivory (#faf9f5) with 1px Border (#e8e6dc), 8px radius, 28px padding. Title in serif 500 at 16px Near Black. Hint underneath in 12px mono Stone. On hover, add a whisper shadow `0 4px 24px rgba(0,0,0,0.05)`. No transform, no color shift."
+- "Build a kami slide cover at 1920×1080. Background ink-blue (#1B365D). Centered title in serif 500 at 96px Ivory (#faf9f5). Below, a 1px ivory rule, 96px wide. Author and date below in serif 500 at 18px Ivory at 70% opacity."
+
+### Iteration Guide
+1. **Start by checking the gray temperature.** If a gray reads cool, the design is no longer kami. Replace with the warm ramp.
+2. **Audit the accent.** If ink-blue covers more than ~5% of the visible surface, reduce — push elements back to Olive or Dark Warm.
+3. **Audit weight.** Any weight above 500 on serif is wrong. Replace with weight 500 and let size carry the contrast.
+4. **Audit italic.** No italic, ever. Swap to ink-blue color or a small tag.
+5. **Audit shadows.** If a shadow is visible at a glance, it's too strong. The only shadows are 1px rings and the `0 4px 24px rgba(0,0,0,0.05)` whisper.
+6. **Tag fills must be solid hex.** If you wrote `rgba(27, 54, 93, 0.18)`, replace with `#E4ECF5`.
+7. **Numbers tabular-nums.** Any column of numbers without `font-variant-numeric: tabular-nums` will look wrong on a print render.
+8. **For slide work, halve tracking and scale macro tokens by 1.6.** Print rhythm is too loose at 1920×1080 without the adjustment.
+
+## Attribution
+
+Aesthetic inspiration drawn from [tw93/kami](https://github.com/tw93/kami) (MIT, © Tw93 and contributors). kami is a Claude skill for typesetting professional documents and slide decks; the tokens, type rules, and "ten invariants" above adapt its print-first design language for use as an Open Design system.