frontend-design-pro

Name: frontend-design-pro
Author: QinghongLin/data2story-skill

$npx mdskill add QinghongLin/data2story-skill/frontend-design-pro

Provides a shared design system for building polished HTML stories.

Designers and programmers need a consistent visual language for editorial stories.
Relies on the Read tool to access the design rule library.
Designer picks a theme and component vocabulary from the library.
Programmer implements the chosen theme as CSS variables and component recipes.

SKILL.md

.github/skills/frontend-design-proView on GitHub ↗

---
name: frontend-design-pro
description: "Shared UI/visual-design rule library for building polished, distinctive, multimedia-rich self-contained HTML stories. The Data2Story Designer and Programmer read it to choose a visual language (theme, type pairing, layout, components, motion) and implement it so every blog looks intentional and editorial, never templated. Use when designing or reshaping a story's look, picking fonts/colors/themes, building a hero/chart/card/map/audio component, adding motion or an interactive, or fixing a visual defect (invisible chart, overflow, broken media, AI-slop look). Not a pipeline stage — a design source consulted by other roles."
allowed-tools: Read
---

# Frontend Design

A shared design system for building **beautiful, distinctive, multimedia-rich** HTML stories. This is not a pipeline stage; it is a library the **Designer** reads to choose a visual language and the **Programmer** reads to implement it, so output looks like an editorial product, not a default template.

## When to use

- **Designer**: before writing `page_rhythm` and per-section visuals, pick a theme and component vocabulary from here. Borrow tokens, layout, and component recipes; record the chosen theme in `designer.json` `page_rhythm`.
- **Programmer**: implement the chosen theme's tokens as CSS `:root` variables and build each visual with the matching component recipe and motion/accessibility rules here.

## Core principles

1. **Editorial, not generic.** Avoid the default-AI look (bootstrap blue, purple gradient hero, everything centered, one system font, evenly-spaced soulless cards). Commit to one bold idea per story. See [`references/themes.json`](references/themes.json) → `anti_patterns`.
2. **Rich media by default.** A story should use multiple channels well — charts, images, video, audio, interactives/maps — each presented with craft, not dumped in. See [`references/media_presentation.json`](references/media_presentation.json).
3. **One system, themed per story.** All color/type/space/shadow flow from CSS `:root` tokens so the whole page is coherent and re-themeable. See [`references/design_tokens.json`](references/design_tokens.json) for tokens and [`references/typography.json`](references/typography.json) for concrete `file://`-safe font-pairing stacks.
4. **Structure carries the reading.** A clear content column, deliberate full-bleed moments, and consistent section rhythm. See [`references/layout.json`](references/layout.json).
5. **Motion and access are part of the design.** Subtle scroll reveals and transitions, always respecting `prefers-reduced-motion`, AA contrast, focus states, and "never autoplay sound." See [`references/motion.json`](references/motion.json) for motion tokens, choreography, accessibility, and the anti-slop checklist.
6. **Self-contained.** Single HTML file; allowed CDNs only (Vega-Embed, Leaflet, optionally D3/PDF.js); inline data; works on `file://`.

## References

- **[`references/design_tokens.json`](references/design_tokens.json)** — color roles, data-color scales, fluid type scale, spacing/radius/shadow, themed via `:root`.
- **[`references/layout.json`](references/layout.json)** — content column, full-bleed breakout, section rhythm, responsive grid, sticky patterns.
- **[`references/components.json`](references/components.json)** — recipes: hero/teaser, stat callouts, card deck, pull quote, chart/map frames, audio players, scrollytelling, before/after, guess-reveal, data table, references footer.
- **[`references/media_presentation.json`](references/media_presentation.json)** — how to present each channel (image, video, audio, chart, map, instance) richly, and the "all five channels by default" doctrine.
- **[`references/themes.json`](references/themes.json)** — ready-made distinctive themes (token presets) and the anti-patterns to avoid.
- **[`references/interaction_playbook.json`](references/interaction_playbook.json)** — the deep interaction/craft playbook: craft principles, centerpiece doctrine, the universal engine (state + render + steps[]), and recipes for explorables/scrollytelling/guess-reveal.
- **[`references/pitfalls.json`](references/pitfalls.json)** — the 错题本 (mistakes-never-to-repeat ledger): real bugs from shipped runs, each with how a role detects it. Read before building.
- **[`references/exemplars/cinematic_flagship.md`](references/exemplars/cinematic_flagship.md)** — a proven cinematic-blog blueprint with copy-paste recipes (pick-a-side hero, accuracy scorecard, cinemagraph hero, continuous backdrop, publish-gate manifest).
- **[`references/abstract_excellence.json`](references/abstract_excellence.json)** — the positive flagship playbook for the dry / abstract / computational topic (chart-led / statistical / non-photographic): reframe hook, signature annotated chart, the reader's own position, disciplined typography, and the runnable-verify layer. Read whenever the topic resolves `is_visual=false` (especially `is_computational=true`) — the analogue of the cinematic recipes for stories with no photographable subject.
- **[`references/typography.json`](references/typography.json)** — font-pairing catalog, `file://`-safe font stacks, and the ban list of generic/default type choices.
- **[`references/finish.json`](references/finish.json)** — the editorial finish layer: the small polish details that lift a page from competent to crafted.
- **[`references/motion.json`](references/motion.json)** — motion tokens, choreography, micro-interactions, accessibility, reduced-motion, performance, and the anti-slop checklist.
- **[`references/quality_rubric.json`](references/quality_rubric.json)** — the shared design-quality rubric authors are scored against.

A story is well-designed when it commits to one clear visual identity, uses several media channels with craft, reads cleanly on mobile and desktop, and could not be mistaken for a default template.

More from QinghongLin/data2story-skill

Skill	Description
analyst	Exhaustively profile a dataset and list ALL possible analyses — distributions, correlations, rankings, trends, group comparisons, anomalies. Reads detective.json for context. Runs after the Detective/Scout, before the Editor. Outputs analyst.json with ana_xx IDs and chart-ready data_tables.
auditor	Audit a generated Data2Story blog for build correctness across ALL modalities by ACTUALLY RENDERING it in a real headless browser (when available) — catching blank/0-width charts, broken/oversized media, desktop+mobile overflow, and dead interactions that source inspection cannot see — then having vision agents review the screenshots, playtesting every interactive, and walking the flagship capability contract. Plus VIEW every image for a wrong/AI-faked subject. Fixes layout in place; sends content-correctness problems back to the owning role. Use at Stage 6 after the Programmer assembles index.html and before the Critic; re-runs each revision round. Triggers: a built index.html exists, or you need to confirm charts/media/interactions actually render.
cinematographer	Design the MANDATORY cinematic scroll experience (every blog ships one): a full-bleed, scroll-driven background — primarily from the Scout's verified real imagery — plus the global motion choreography, so the narrative unfolds like a film as the reader scrolls. Owns the BACKGROUND layer + page-level motion (not the Designer's per-section visuals, not the Interaction centerpiece — it stages them inside the scroll). Outputs cinematographer.json (cin_xx scenes). There is no off path: a topic with no sourceable real imagery falls back to a generative-atmosphere or data-driven-spine background, never to a bare column.
copywriter	Name the piece — re-write the masthead (headline + standfirst + kicker), every section title, and every figure/photo/table caption to a research-driven titling standard, killing the AI-tell patterns (the 'flat statement. flat counter-statement.' two-beat above all) a competent default falls into. Reads editor.md/json + analyst.json + the resolved topic_profile; writes copywriter.json — STRINGS ONLY (masthead{headline,standfirst,kicker}, items{edt_xx:{title}, des_xx:{caption}}), each backed by a real ana_. Names, never edits: it touches no finding, no number, no data- id, no layout — so the Verify layer is untouched and the Programmer renders the masthead + figcaptions from copywriter.json verbatim. Runs at Stage 3.5, after the Editor, before the Designer.
critic	Review a finished Data2Story blog against the 5 quality rubric dimensions (visual_design, narrative_pacing, data_method_transparency, claim_data_alignment, insight_value), score each 1-7 with on-page evidence, and emit critic.json with pass/fail + targeted, surgical send-back instructions. Verifies every load-bearing claim/asset against its traceability chain before scoring; applies the caveat-survival, honest-accuracy, and third-party-attribution caps. Does NOT rewrite content — scores and sends back. Use at Stage 6.5 after the Auditor and after verify.py has produced verifier.json; re-runs each revision round. Triggers: a built index.html plus verifier.json exist, or you need to judge whether the article is actually good.
data2story	Data Journalist Agent (Data2Story) — orchestrator: turn a dataset into a blog. Runs detective → analyst → editor → designer → programmer → auditor → inspector in sequence. Creates a versioned project folder for each run.
data2story-pro	Use to turn a dataset into a verifiable multimedia blog (a data story / data-driven article / interactive dashboard from a dataset). Orchestrator for the Data Journalist Agent (Data2Story): a 7-team newsroom (14 agents) running detective → scout → analyst → imagineer → editor → copywriter → designer → interaction → hero → cinematographer → programmer → auditor → critic → inspector in sequence. Trigger when the user hands over a dataset (CSV/JSON/folder/path) and wants a published story, blog post, or interactive report built from it. Creates a versioned project folder per run.
dataviz-craft	A shared reference library for editorial-grade data-visualization craft — Vega-Lite-first with a D3 fallback for charts Vega-Lite can't express. Read by the Designer at chart selection (intent → ranked chart type), the Programmer at implementation (editorial Vega-Lite recipes, annotation layers, axis/label de-clutter, encoding craft), and the Auditor/Critic for chart-quality review. It encodes the FT Visual Vocabulary intent taxonomy, the Cleveland–McGill channel-accuracy ordering, the BBC bbplot de-clutter ruleset, and colorblind-safe encoding rules. Not a pipeline stage — a craft source, like frontend-design.
designer	Read editor.md, editor.json, and analyst.json. Make data-driven creative visual decisions for every section — teaser, charts, images, videos, audio, maps, and interactive demos when they fit the data. Generate selected assets. No HTML. Outputs designer.json with des_xx IDs.
detective	Research external context for a dataset — domain background, history, related studies, and why this data matters. Outputs detective.json (structured findings with det_xx IDs) before any analysis begins.