Files
2026-10-12 17:07:38 -03:00

66 lines
8.7 KiB
Python

"""Writes DESIGN_SYSTEM.md from the component registry (names, captions, text layers) + hand-written guidance."""
import re, sys
sys.path.insert(0, ".")
import ds_components as C
from ds_foundations import COLOR_GROUPS
from ds_common import EXTRA_VARS
LEAF = re.compile(r'layer-name="([^"]+)"[^>]*>([^<]+)</div>')
out = ["# Interview design system (PaperCraft page `Design System`)", "",
"Generated by `design_system.py` + `gen_manifest.py`. Main components are top-level frames on the `Design System` page (library area, right of the doc sections, x >= 1560). Documentation sections: `Section / Colors`, `Section / Typography`, `Section / Spacing`, `Section / Radius & Shadow`, `Section / Page Layout`, `Section / Components` (captioned instances of everything).", "",
"## How to use", "",
"1. On your page: `papercraft-cli call import_components '{\"fromPageId\":\"<Design System page id>\",\"pageId\":\"<your page id>\"}'` (skips names already there; if you delete a copy and re-import, its instances lose overrides).",
"2. Place: `<x-paper-instance component=\"Button / Primary\" overrides='{\"Label\":\"Save\"}'/>` or `inst_html(\"Button / Primary\", Label=\"Save\")` from pc.py.",
"3. Overrides JSON: key = exact layer name inside the component (first match), value = string (text) or object (CSS camelCase styles, e.g. `{\"Label\":{\"color\":\"var(--color-error)\"}}`). Hide a part: `{\"Col 5\":{\"display\":\"none\"}}`.",
"4. The instance root accepts a `style` attribute: `style=\"width:720px\"`, `style=\"background-color:var(--color-avatar-purple)\"`, `style=\"opacity:.5\"` (disabled).",
"5. Icons inside components cannot be recolored or swapped by overrides (vector layers). That is why the sidebars exist as one variant per active item. For anything else, compose in raw HTML with the recipes below.",
"6. Components hug their content (fixed width where noted). To stretch, set `style=\"width:Npx\"` on the instance. Uppercase labels (table headers, Stat label, sidebar group labels) are typed uppercase: text-transform is not supported.",
"7. Instances are page-local; no variants/properties exist, so every variant is a separate component.", ""]
out += ["## Components", ""]
for g, names in C.GROUPS.items():
out += [f"### {g}", "", "| Component (exact name) | Looks like | Text layers (override keys) |", "|---|---|---|"]
for n in names:
html = dict(C.SPECS)[n]
keys = []
for k, t in LEAF.findall(html):
if k not in keys:
keys.append(k)
keys = [f"`{k}`" for k in keys]
out.append(f"| `{n}` | {C.NOTES.get(n, '')} | {', '.join(keys) or '(none)'} |")
out.append("")
out += ["## Style-override tips", "",
"- **Recolor an Avatar**: `style=\"background-color:var(--color-avatar-purple)\"` on the instance (palette: brand-primary, avatar-purple, avatar-teal, warning, avatar-pink, success, avatar-orange, avatar-indigo; the app picks by a hash of the name). Set initials with `{\"Initials\":\"PI\"}`.",
"- **Active sidebar item**: use the variant `Admin Sidebar / <Item> Active` (Dashboard, Challenges, Question bank, Sessions, Schedule, Configuration, Rubric) or `Candidate Sidebar / Home Active` / `My interview Active`. Plain `Admin Sidebar` / `Candidate Sidebar` have no active item. Manual route (text/bg only; icon stays gray): `{\"Nav / Sessions\":{\"backgroundColor\":\"var(--color-brand-primary)\"},\"Nav Label / Sessions\":{\"color\":\"var(--color-text-inverse)\",\"fontWeight\":600}}`. User name/email: `User Name`, `User Email`, `User Initials`, `User Role Tag Label`.",
"- **Score Bar**: set `Fill` width in px of the 160px track: `{\"Fill\":{\"width\":\"100px\"}}`; recolor `{\"Fill\":{\"backgroundColor\":\"var(--color-avatar-purple)\"}}`; thinner: `{\"Fill\":{\"height\":\"4px\"}}` plus root `style=\"height:4px\"`.",
"- **Segmented / Ant Segmented**: pick the variant whose `Active N` matches; edit `Option 1..n`.",
"- **Tabs / Bar**: pick `Active N` variant; edit `Tab N Label`. Bars have a 1px divider under them.",
"- **Stat**: `Label` (uppercase), `Value`, `Delta`, `Trend`, `Delta Arrow` (use `Stat / Orange Down` for a negative delta). Sparkline shape is fixed.",
"- **Pill / Tag / Badge status colors**: choose the tone component. Custom: `{\"Label\":{\"color\":\"var(--color-tag-red-fg)\"}}` and root `style=\"background-color:var(--color-tag-red-bg);border:1px solid var(--color-tag-red-bd)\"`.",
"- **Data Table / Header Row, Row, Ant Table rows**: 5 equal flex cells `Col 1..5` / `Cell 1..5`; for fewer columns hide the trailing ones with display:none; width via `style`. For rows with Tags/Avatars compose raw HTML in a `<table>` and reuse `Tag / ...` instances in cells. Wrap a table in a Card-like frame: radius-lg, 1px border-light, overflow hidden.",
"- **Inputs**: `Value` is the text (placeholder color by default; use `Input / Filled` for values). Width via instance style. `Form Field*` has `Label`, `Required Mark`, `Value`, `Help`.",
"- **Disabled button**: `style=\"opacity:.5\"` on the instance. **Block button**: `style=\"width:100%\"` (add `justify-content:center`: already centered).",
"- **Card with gradient** (dashboard Awaiting review): build raw: `background:linear-gradient(180deg,#fffdf5,#ffffff)`.", "",
"## Recipes for raw HTML (when no component fits)", "",
"- Card: `display:flex;flex-direction:column;padding:var(--spacing-lg);background:var(--color-bg-elevated);border:1px solid var(--color-border-light);border-radius:var(--radius-lg);box-shadow:var(--shadow-sm)`.",
"- Button with icon: row, gap 8px, height 34px (sm 28, lg 40), padding 0 16px, radius-md; icon 14-16px via `<x-paper-icon name=\"phosphor:plus\" size=\"16\" color=\"var(--color-text-inverse)\"/>`.",
"- Page frame 1440x900: left `Admin Sidebar ...` (248x900) + main column 1192 wide: `Admin Shell Header` (about 102px tall) + content (padding 24, bg-layout, max-width 900/1100 centered).",
"- Modal overlay: full-screen frame `background:var(--color-bg-overlay)` with a `Modal` instance centered.",
"- Section titles inside cards: `Section Title` / `Section Title / With Action` instances.", "",
"## Variables (use as `var(--name)`)", "",
"Core tokens exist in the project (from tokens.css, same names minus the leading `--`): color-brand-primary, color-brand-secondary, color-bg-layout, color-bg-elevated, color-bg-sider, color-bg-selected, color-bg-overlay, color-border, color-border-light, color-border-strong, color-text-primary, color-text-secondary, color-text-disabled, color-text-inverse, color-text-link, color-success, color-warning, color-error, color-info, color-diff-added, color-diff-removed, color-diff-neutral, color-code-bg, color-code-fg; spacing-xs/sm/md/lg/xl/xxl (4/8/16/24/32/48), page-padding (24), page-padding-lg (48), page-max-width-xs/sm/md/lg/xl/narrow/default/wide (480/420/720/900/1100/720/900/1100), font-size-xs..xxl (12/14/16/18/20/24), radius-sm/md/lg (4/8/12), shadow-sm/md/lg, z-base/dropdown/modal/toast (1/1000/1050/1100).", "",
"Note: multi-value shorthands (`padding:var(--spacing-md) var(--page-padding)`) are NOT resolved by write_html: use single-value padding with var, or literal px for shorthands. Single `var(--spacing-*)`, `var(--radius-*)`, `var(--shadow-*)`, `var(--font-size-*)` work.", "",
"### Extra color variables added by the Design System page", ""]
for g, names in COLOR_GROUPS.items():
ex = [n for n in names if n in EXTRA_VARS]
if ex:
out.append(f"- **{g}**: " + ", ".join(f"`{n}` {EXTRA_VARS[n]}" for n in ex))
out += ["", "### Font stack and type scale", "",
"Inter only (regular/bold; weights 500 render regular, 600+ bold). Sizes: 12 labels/tags/table headers, 14 body, 16 section/card title, 24 page title (600), 30 stat value (700), 15/16 brand name.", "",
"## Known deviations from the source", "",
"- Pill in the code is the filter chip (active/inactive); there are no tone variants (`Pill / Success` does not exist). Tones are `Tag`.",
"- `lint_design`: remaining errors/warnings are faithful brand colors (white on #1677ff 4.1:1, success green on white, etc.), control heights under 44px (34/32px as in the source), and svg-internal names. Not changed on purpose.",
"- Text under 12px in the source (10.5/11) is rendered at 12; padding off the 4px grid was snapped (11->12, 18->16, 14->16, 9->0 with fixed 36px item height).",
"- Main components cannot be nested in the `Section / Components` frame (create_component/import_components need top-level frames), so the section shows instances; masters are in the library area.", ""]
open("DESIGN_SYSTEM.md", "w").write("\n".join(out))
print(len(out))