Files
Willie 67639e54f8 build(ui): adopt Oxc formatting and type-aware linting (#956)
Format the dashboard with Oxfmt and use tsrs for project builds and Oxlint type analysis. Fix the initial typed findings and check formatting and typed lint in CI to keep new changes consistent.
2026-11-18 22:37:24 +08:00

214 lines
9.0 KiB
Python

#!/usr/bin/env python3
"""Export the dashboard's Clean tokens as a Design System tokens.json.
ui/src/components.css stays the source of truth. This prints the tokens.json
the "Skillshare Dashboard" design system artifact holds, so the artifact can be
re-synced after the CSS changes instead of being rebuilt by hand.
python3 scripts/design/tokens.py [--out FILE]
"""
import argparse
import datetime
import json
from pathlib import Path
import re
import subprocess
import sys
ROOT = Path(__file__).resolve().parents[2]
CSS_PATH = "ui/src/components.css"
LIGHT = ":root:not([data-theme='playful'])"
DARK = LIGHT + ".dark"
# Every Clean color variable needs a usage note here, or the export fails.
COLOR_USAGE = {
"bg": "Page background behind every screen.",
"side": "Sidebar background.",
"surface": "Cards, lists, inputs, dialogs: anything framed on top of bg.",
"sunken": "Recessed areas inside a surface: list headers, group headers, notes, tags, icon tiles.",
"ink": "Primary text and headings on bg, surface or sunken.",
"ink-2": "Secondary text: descriptions, inactive tabs, button labels.",
"ink-3": "Tertiary text: captions, counts, paths, placeholders. Lightest text allowed.",
"line": "Frames and dividers between sections and rows.",
"line-2": "Control borders: buttons, inputs, switches when off, dashed add buttons.",
"frame": "1px border around a card or list box (--frame in code).",
"sep": "1px separator between rows inside a list (--sep in code).",
"pri": "Primary button fill and switch-on track. Clean's primary is ink, never a hue.",
"on-pri": "Text and icons on pri.",
"accent": "Links, focus rings, 'pending' markers. The only hue Clean uses for interaction.",
"accent-bg": "Selected row background; tint behind accent text.",
"sel": "Selected nav item and menu hover; text on it stays ink.",
"sel-ink": "Text on sel.",
"ok": "Status dot and text: synced, loaded, on.",
"ok-bg": "Tint behind ok text.",
"warn": "Status: needs attention, not installed, drift.",
"warn-bg": "Tint behind warn text; warning notes.",
"bad": "Errors, destructive actions, removed diff lines.",
"bad-bg": "Tint behind bad text; error notes.",
"c-skill": "Kind tile icon for skills (.ss-cat.skill). Kind colors only appear on these small tiles.",
"c-skill-bg": "Kind tile background for skills.",
"c-agent": "Kind tile icon for agents.",
"c-agent-bg": "Kind tile background for agents.",
"c-extra": "Kind tile icon for extras.",
"c-extra-bg": "Kind tile background for extras.",
"c-mcp": "Kind tile icon for MCP servers.",
"c-mcp-bg": "Kind tile background for MCP servers.",
"c-target": "Kind tile icon for targets.",
"c-target-bg": "Kind tile background for targets.",
"c-plugin": "Kind tile icon for plugins and Pi packages.",
"c-plugin-bg": "Kind tile background for plugins.",
"glass-menu": "Frosted menus and floating hints (with --mat-menu blur).",
"glass-bar": "Frosted sticky toolbar over scrolling content (with --mat blur).",
}
# Color-valued variables deliberately left out of the design system.
COLOR_SKIP = {"line-soft", "dots"}
# Whole border shorthands ("1px solid #ECE9E3"); the design system records their color.
BORDER_SHORTHANDS = {"frame", "sep"}
RADIUS_USAGE = {
"r-tag": "Tags and small chips.",
"r-ctl": "Inputs, icon buttons, icon tiles.",
"r-box": "Cards, lists, dialogs.",
"r-btn": "Buttons are pills.",
}
SHADOW_USAGE = {
"sh-box": "Cards.",
"sh-float": "Menus, toasts, sticky action bars.",
"sh-dialog": "Dialogs.",
}
def block(css, selector):
match = re.search(r"^[ \t]*" + re.escape(selector) + r" \{", css, re.M)
if not match:
raise ValueError(f"{CSS_PATH}: no rule for {selector}")
return css[match.start():css.index("}", match.start())]
def declarations(text, prefix=""):
return {m.group(1): m.group(2).strip() for m in re.finditer(prefix + r"([a-z0-9-]+):\s*([^;]+);", text)}
def css_vars(css, selector):
return declarations(block(css, selector), "--")
def is_color(value):
return value.startswith("#") or value.startswith("rgb")
def font(shorthand):
weight, size, line = re.match(r"(\d+) ([\d.]+px)/([\d.]+)", shorthand).groups()
return {"fontSize": size, "lineHeight": float(line), "fontWeight": int(weight)}
def color_value(name, light, dark):
if name in BORDER_SHORTHANDS:
return {"light": light[name].split()[-1].lower(), "dark": dark[name].split()[-1].lower()}
return {"light": light[name].lower(), "dark": dark.get(name, light[name]).lower()}
def colors(light, dark):
unnoted = sorted(n for n, v in light.items() if is_color(v) and n not in COLOR_USAGE and n not in COLOR_SKIP)
if unnoted:
raise ValueError(f"{CSS_PATH}: add a usage note in scripts/design/tokens.py for --{', --'.join(unnoted)}")
return [{"name": n, "value": color_value(n, light, dark), "usage": u} for n, u in COLOR_USAGE.items()]
def type_scale(css, light):
body = declarations(block(css, "body"))
btn = declarations(block(css, ".ss-btn"))
note = declarations(block(css, ".ss-note"))
cnt = declarations(block(css, ".ss-cnt"))
name = declarations(block(css, ".ss-r .nm.m"))
tag = declarations(block(css, ".ss-tag"))
return {
"fonts": [],
"families": {"sans": light["f"], "mono": light["fm"]},
"groups": [
{"name": "Headings", "family": "sans", "styles": [
{"name": "h1", **font(light["h1"]), "letterSpacing": light["h1-track"]},
{"name": "h2", **font(light["h2"]), "letterSpacing": light["h2-track"]},
]},
{"name": "Text", "family": "sans", "styles": [
{"name": "body", **font(body["font"])},
{"name": "small", "fontSize": note["font-size"], "lineHeight": float(note["line-height"]), "fontWeight": 400},
{"name": "button", **font(btn["font"])},
{"name": "caption", **font(cnt["font"])},
]},
{"name": "Mono", "family": "mono", "styles": [
{"name": "mono-name", "fontSize": name["font-size"], "lineHeight": 1.4, "fontWeight": int(name["font-weight"]), "letterSpacing": name["letter-spacing"]},
{"name": "mono-tag", **font(tag["font"])},
]},
],
}
def spacing(css):
wrap = declarations(block(css, ".ss-wrap"))
row = declarations(block(css, ".ss-r"))
btn = declarations(block(css, ".ss-btn"))
return [
{"name": "page-max", "value": wrap["max-width"], "usage": "Max width of the page column (.ss-wrap)."},
{"name": "page-gap", "value": wrap["gap"], "usage": "Gap between page sections; never add margins on top of it."},
{"name": "row-height", "value": row["min-height"], "usage": "Minimum height of a list row (.ss-r)."},
{"name": "row-pad", "value": row["padding"].split()[-1], "usage": "Horizontal padding inside list rows and headers."},
{"name": "control-height", "value": btn["height"], "usage": "Buttons and inputs at default size."},
]
def shadows(light, dark):
out = []
for n, usage in SHADOW_USAGE.items():
if dark.get(n, light[n]) != light[n]:
usage += f" Dark: {dark[n]}."
out.append({"name": n, "value": light[n], "usage": usage})
return out
def export(css, ref=None, today=None):
light, dark = css_vars(css, LIGHT), css_vars(css, DARK)
return {
"name": "Skillshare Dashboard",
"version": 1,
"meta": {
"source": "github",
"repo": "runkids/skillshare",
"ref": ref,
"package": "ui",
"paths": {"tokens": [CSS_PATH]},
"synced": today or datetime.date.today().isoformat(),
"scope": "Clean style only (light + dark). Playful is not included.",
},
"color": {"themes": [{"id": "light", "name": "Clean Light"}, {"id": "dark", "name": "Clean Dark"}], "tokens": colors(light, dark)},
"type": type_scale(css, light),
"spacing": {"tokens": spacing(css)},
"radius": {"tokens": [{"name": n, "value": light[n], "usage": u} for n, u in RADIUS_USAGE.items()]},
"shadow": {"tokens": shadows(light, dark)},
}
def git_ref():
try:
sha = subprocess.run(["git", "rev-parse", "--short", "HEAD"], cwd=ROOT, capture_output=True, text=True, check=True).stdout.strip()
branch = subprocess.run(["git", "branch", "--show-current"], cwd=ROOT, capture_output=True, text=True, check=True).stdout.strip()
except (OSError, subprocess.CalledProcessError):
return None
return f"{branch or 'HEAD'}@{sha}"
def main(argv=None):
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--out", help="write here instead of stdout")
args = parser.parse_args(argv)
text = json.dumps(export((ROOT / CSS_PATH).read_text(), ref=git_ref()), indent=2, ensure_ascii=False) + "\n"
if args.out:
Path(args.out).write_text(text)
else:
sys.stdout.write(text)
if __name__ == "__main__":
main()