@cychien/ezdesign 0.0.0-stage → 0.8.1

package/skills/ezdesign/reference/design.md

@@ -0,0 +1,247 @@
+# Write the project's DESIGN.md
+
+> Only for a turn whose prompt says 增強設計 (the design harness) is on for it, or a request that
+> asks for it by name. In any other turn, handle the request as if you had never read this file.
+
+## What this file is
+
+`DESIGN.md` at the project root captures the project's visual language in broad strokes: the
+character of its colour, type, space and form, and the handful of values that anchor them. It is a
+direction agents start from when they design, not a specification they are held to. **Keep it
+broad.** A file that settles every size, step and shadow leaves the work nothing to decide, and
+everything made from it comes out looking alike. The fine detail - the full type ramp, the spacing
+scale, the shadow recipes, each component's values - lives in the design system and the code, where
+the components step and the work itself put it.
+
+It follows the DESIGN.md format (`npx -y -p @google/design.md designmd spec`): YAML frontmatter
+carrying machine-readable tokens, then markdown sections in a fixed order with canonical headings.
+Here **the tokens are anchors, not a full set**: the few values the language is recognised by.
+Sections may be omitted when irrelevant, but the ones present keep the spec's order and exact
+headings, so the file stays portable across DESIGN.md-aware tools.
+
+**Components are not defined here.** A markdown file cannot carry a component's states, variants
+and behaviour completely, so the components step turns this file's language into the stack's own
+design system and a component set, and records where in `.ezdesign/config.json`. This file
+therefore carries no `components:` group in its frontmatter and no `## Components` section; a
+reader who needs a component goes to the design system. See [components.md](components.md).
+
+## The frontmatter
+
+```yaml
+---
+name: <project title>
+description: <one-line tagline>
+colors:
+  primary: "#b8422e"
+  canvas: "#faf7f2"
+  ink: "#1f1d1a"
+typography:
+  display:
+    fontFamily: "Cormorant Garamond, Georgia, serif"
+    fontWeight: 300
+  body:
+    fontFamily: "Inter, system-ui, sans-serif"
+    fontSize: "1rem"
+rounded:
+  soft: "8px"
+omitted:
+  - spacing
+---
+```
+
+- **Anchors only.** The colours the language is recognised by - the ground, the ink, the accent or
+  two - and not every tint and state. One entry per typographic role that has a character of its
+  own, usually display and body, with its family and the one or two properties that define it. A
+  radius when the form language has one. No scale: a ramp of steps is the design system's.
+- **List what you leave out under `omitted`**, so the linter reads a missing group as a decision.
+- **Keys describe, not enumerate**: `oxblood-deep`, `canvas`, `ink-mute`, not `blue-800`,
+  `gray-100`. The one exception is the main accent, which goes under `primary` because the linter
+  expects it. Use the names the project already uses when it has them; do not rename to Material
+  defaults.
+- **Colours accept any valid CSS colour string.** Hex is the portable default, but keep an
+  incumbent `rgb()`, `hsl()` or `oklch()` when that is the project's normative source. One format
+  per token, and never the same token restated in prose with a different value.
+- **The schema has no place for shadows, motion or breakpoints.** When one is part of the
+  character, describe it in prose. Do not invent a top-level group for them.
+
+## The body: canonical sections, in order
+
+1. `Overview`
+2. `Colors`
+3. `Typography`
+4. `Layout`
+5. `Elevation & Depth`
+6. `Shapes`
+7. `Do's and Don'ts`
+
+The format also defines `Components` between Shapes and Do's and Don'ts; this harness leaves it
+out on purpose. Omit any other section the project has nothing real for, rather than filling it.
+Every section is a short paragraph or a few bullets. The whole file reads in a couple of minutes.
+
+## Step 1: Load current state
+
+- `PRODUCT.md` comes first. If it is missing, run [product.md](product.md) and come back: the
+  Overview's voice and the visual constraints come from it.
+- Read `.ezdesign/config.json` for the stack and the browser tool. If it is missing or names no
+  browser tool, run [stack.md](stack.md) and come back.
+- If `DESIGN.md` already exists, **do not silently overwrite it**. Show the user what is there, and
+  ask whether to refresh, overwrite or merge. Use the structured question tool when available;
+  otherwise ask and wait.
+- Decide the path by scanning first (Scan mode, Step 2). If the scan finds no tokens, no component
+  files and no rendered site, offer Seed mode; do not switch silently.
+
+## Scan mode: read the language the project already speaks
+
+The project has tokens, components or rendered output. This is the default.
+
+### Step 2: Look at what exists
+
+Read the sources for the values the project defines, and the rendered page for which of them
+carry it:
+
+- **The sources**: CSS custom properties, the Tailwind config or `@theme` block, CSS-in-JS theme
+  files, token files, the global stylesheet, and the main components - button, card, input,
+  navigation, dialog.
+- **The rendered page**: at the url your prompt gives, otherwise at the dev server, which you
+  start if it is not up. Measure it with `node <skill>/scripts/page.mjs measure <url>`, where
+  `<skill>` is the folder above this file's `reference/`: it renders the page at desktop and at
+  390px and tallies what the visible elements use - text, background and border colours, each
+  background's share of the screen, families, sizes, weights, line heights, radii, shadows,
+  padding, gaps and container widths - with the project's own tokens. **Frequency** is what a
+  stylesheet cannot tell you: the colour on three hundred elements is the ground, the one on two is
+  the accent, a rule matching nothing is not in the language, so let the counts say what dominates.
+  A `redirected` field means it measured the page the url sent it to, a sign-in most of the time,
+  not the product: measure a path that stays, or lean on the sources.
+  Look at it too: `node <skill>/scripts/page.mjs shots <url> <dir>` writes a desktop and a mobile
+  screenshot into a folder outside the project. Only when the script cannot run - there is no
+  Chrome - do the same with the browser tool.
+
+Where a source and the page disagree, the page is what users see.
+
+### Step 3: Name the character
+
+From what you found, say what the language is, not everything it contains:
+
+- **Colour**: the ground, the ink, the accent, and how much of a screen the accent gets.
+- **Type**: the pairing and the contrast between display and body; how large, how tight, how
+  loud the scale runs. Not each step.
+- **Space**: dense or airy, and whether the rhythm is even or varied.
+- **Depth and form**: flat, layered or lifted; sharp, softened or round.
+
+Stop at what defines it. A value that appears once is drift, and a value the language does not
+depend on belongs to the design system.
+
+### Step 4: Ask for what cannot be extracted
+
+The rest is judgment, and the user is the client. Ask in two rounds of at most three questions
+each, waiting between rounds, each question led by your own proposal so the client corrects rather
+than composes. Use the structured question tool when available; otherwise ask and wait. Choose the
+questions for this project from these, skip any the page already answers plainly, and add one of
+your own when the project needs it:
+
+- **Overview voice**: mood adjectives, the aesthetic philosophy in two or three sentences, and the
+  anti-reference - what this must never be mistaken for.
+- **Elevation philosophy**: flat, layered or lifted.
+
+Carry a line from `PRODUCT.md` only when it is a durable brand commitment that actually constrains
+the visual system. Page strategy and surface concepts do not belong here.
+
+### Step 5: Write DESIGN.md
+
+The frontmatter, then the body:
+
+```markdown
+# Design System: [Project Title]
+
+## Overview
+
+[Two short paragraphs, in plain words: personality, density and aesthetic philosophy, and the
+anti-reference. No named metaphor - a metaphor becomes the idea every later design reaches for.
+End with a short **Key Characteristics:** list, three to five bullets.]
+
+## Colors
+
+[The palette's character in a sentence or two, then one line per anchor.]
+- **[Descriptive Name]** (`{colors.canvas}`): [Its role, and roughly how much of a screen it gets.]
+
+## Typography
+
+**Display Font:** [Family] (with [fallback])
+**Body Font:** [Family] (with [fallback])
+
+[The pairing's personality, and how the scale behaves - its contrast and its loudness - in one or
+two sentences. Not a list of steps.]
+
+## Layout
+
+[Density and rhythm, and the spatial idea in a sentence or two.]
+
+## Elevation & Depth
+
+[Flat, layered or lifted, in a sentence or two. "No shadows" is said explicitly, with how depth is
+conveyed instead.]
+
+## Shapes
+
+[The form language in a sentence or two.]
+
+## Do's and Don'ts
+
+### Do:
+- **Do** [a tendency the language has].
+
+### Don't:
+- **Don't** [a direction the language is not, which the incumbent system or the user confirmed].
+```
+
+### Step 6: Lint, confirm, refine
+
+Run `npx -y -p @google/design.md designmd lint DESIGN.md` and fix what it reports, in the
+document. Writing this file changes no other file: measuring a page turns up things that are wrong
+with it, and they are the document's subject, not your to-do list.
+
+Then show the user what you wrote, point out the creative choices that were yours (the colour names
+you gave the palette, the voice) and which parts you asked rather than measured, and offer to revise a section. When
+this step runs as part of a larger request, put that offer in one line at the end of its reply
+instead, and do not stop to wait for an answer.
+
+## Seed mode: a visual language before there is code
+
+### Step 1: `PRODUCT.md`
+
+It is the prerequisite. If it is missing, run [product.md](product.md) and come back.
+
+### Step 2: Derive and write
+
+Propose a visual language from `PRODUCT.md`, and discuss it with the user before writing. The
+product's job sets the density and the register of the type: a dashboard for people who read
+numbers all day is dense, with a small, tight body scale (12px and 14px labels are right there); a
+brochure for a first visit is airy, with a large display scale and few colours. The brand
+commitments set the colours and marks that are fixed; everything else is a proposal, led by you and
+confirmed by the client in rounds of at most three questions. Write the same file as Scan mode,
+with the anchors you proposed as the frontmatter, and mark it as a seed in the Overview. Re-run in
+Scan mode once there is code.
+
+## Style guidelines
+
+- **Character over quantity.** Say what the language is like, and give the value only where it is
+  the anchor. A reader should come away knowing what belongs and what does not, with the decisions
+  inside that left to them.
+- **Tendencies, not requirements**: "leans on", "mostly", "reaches for". The file is a direction;
+  write it as one.
+- **Descriptive over technical**: "Gently curved edges (8px)" over `rounded-lg`. Lead with the
+  description, put the value in parentheses.
+- **Specific to this product.** Prose that would read the same pasted onto another product has
+  captured nothing.
+
+## Pitfalls
+
+- Do not paste raw class names; translate them.
+- Do not write out scales: no type ramp, spacing scale, shadow recipe or per-state colour. They
+  are the design system's.
+- Do not document components here; they are the components step's.
+- Do not overwrite an existing `DESIGN.md` without asking.
+- Do not duplicate `PRODUCT.md`; this file is strictly visual.
+- Do not rename or paraphrase the canonical headings: `Colors`, not "Color Palette"; `Typography`,
+  not "Typography Rules". Tooling parses the exact headers.
+- Do not add frontmatter groups outside `colors`, `typography`, `rounded`, `spacing` and `omitted`.

package/skills/ezdesign/reference/inspiration.md

@@ -0,0 +1,125 @@
+# Search the inspiration database
+
+> Only for a turn whose prompt says 增強設計 (the design harness) is on for it, or a request that
+> asks for it by name. In any other turn, handle the request as if you had never read this file.
+
+## What it is
+
+A curated collection of interfaces that work, each entry carrying the reason it works and the case
+where it would be the wrong choice. Every entry is the work of some of the best product designers in
+the world, chosen by hand because it is good: study it the way a designer studies a master's work,
+not the way you skim an average page. It is searched by meaning - a description of what the piece has
+to show - and entries carry tags in their curator's own words (`onboarding`, `dark popover`), which
+nudge a search when you name one. It is an outside source: nothing in `PRODUCT.md` or `DESIGN.md` is decided by it or written in its
+words. The collection is not in this skill or in the project; the commands below query it, and you
+see what you asked for.
+
+## The commands
+
+```
+npx -y @cychien/ezdesign@latest inspire --query "<what the piece has to show>" [--tag onboarding] [--limit 5]
+```
+
+A `--query`, `--tag`, or both. A search prints a block per result: what it is, its tags, `Shows:`
+(what the entry is), `Components:` and `Actions:` (what is on it, and what can be done there),
+`Why it works:` and `Wrong when:`, then local paths to its images and, when the entry has it,
+`code:` - a working implementation of it. `(approximate)` in the heading means that entry was read
+off a screenshot, so its inventory is an estimate rather than a reading. The images and the code
+are downloaded to disk, so open them the way you open any file - when the steps below say to.
+
+There is no fixed list of tags, so lean on the query: it finds by meaning, and a tag you guess only
+helps when some entry happens to carry it.
+
+It works without a review session, a daemon or a dev server. It needs a token, stored once by
+`npx -y @cychien/ezdesign@latest login`.
+
+When the prompt names the ezdesign command to run, run that one instead of `npx -y @cychien/ezdesign@latest`.
+Never look for another copy or version of ezdesign to run - a repository checkout, a global install,
+a different package version: the command you were given is the only one.
+
+## How to search
+
+- **A batch.** Write the query first: one or two sentences saying what the piece has to show - the
+  elements on it, the register its wording is in, the actions it offers. "A settings page with a
+  two-column form, a destructive delete behind a confirm dialog, labels in Traditional Chinese."
+  Run it once, with `--limit 5`. The design takes one direction, but its moves may come from more
+  than one result.
+- **An explore.** Search only for a variant whose direction would gain from a precedent; a variant
+  does not need one, and the round is about arrangement, not inspiration.
+- **A plain request.** Even "a pricing table" is a query: `--query "a pricing table"` finds it by
+  meaning.
+
+## What to take from a result
+
+A result need not match the request: one that covers most of it, or one part of it well, is a
+result, since nothing in the collection was made for this product. Do not run the search again
+because the first answer was not a fit.
+
+**Learn why it works, and how it is made.** Every entry is the work of an outstanding designer, so
+study it the way a designer studies a master's work, for both. The intent: what each element and
+pattern is there to do for the person using it - why this surface is dark, why this gap is wider
+than that one, why the description stops where it does, why the action sits there - and what would
+go wrong without it. The surface, just as closely: how it arranges and presents the information,
+and the refined details that make it look finished - how a label sits against its value, how a
+group is framed, the size steps between a title, its text and its action, a subtle ground or edge.
+That is where much of a precedent's value is, and what your first idea usually lacks. `Why it
+works:` names the move; the image and the code show how it is carried out. Take a result seriously
+before you judge it: a part you leave out is one you understood and found wrong for this product,
+and your reply says why.
+
+Read a result in two steps, and go on to the second only for the results you learn from:
+
+1. **The text and the first image**, of every result. `Shows:`, `Components:` and `Actions:` say
+   which part of your request it covers, `Why it works:` names the move, and `Wrong when:` says when
+   it is the wrong choice; the first image is the whole piece at desktop size, and shows the move.
+   Judge the direction by both: the text says what an entry is, the image whether it looks the part.
+   The other images are the phone and further states: open as many of them as the judgment needs.
+2. **The code**, of each result you learn from - one or several - and of none you set aside. A
+   screenshot is one moment, and a precedent understood from it alone is understood wrong: the code
+   is the precedent working. Read the whole file, not its first lines - the states and the motion are
+   usually further down. Read it to understand how the piece behaves, not to paste it: what appears
+   only on hover or focus, what is hidden until chosen, what moves, and the proportions behind what
+   the image shows.
+
+**Mind the motion.** The code shows what moves, when, how far and on what curve. Work out what each
+motion is for - confirming an action, showing where something came from or went, drawing the eye to
+what changed - and use motion in your piece only where it does that same job here. Keep it as short
+and quiet as the job allows, in the easing the principles give, and let it fall away under
+`prefers-reduced-motion`. Motion that is only there because the precedent had it is decoration.
+
+**Make it yours.** Bring what you learned into a design of your own for this product: the intent
+carried over, expressed in this project's tokens, type, components and motion, and held to
+`baseline.md`. Carry relationships, not numbers: the space between groups against the space inside
+them, the padding a surface gives its content, the size steps between a title, its text and its
+action - each in the project token nearest in role, keeping the proportion, so a gap half its
+card's padding stays half. The entry's palette, fonts, exact values and content do not transfer.
+The piece should read as this product's own, not as the precedent in a new skin.
+
+**Starting from a pattern.** When one pattern is right for this case - it solves the problem in
+front of you, and `Wrong when:` does not describe this product - you may start from it: take its
+structure as the base, then adapt it to this product's content, its point and hierarchy, and its
+tokens. Even then it is a starting point, not a copy: every part you keep, you keep because you know
+why it works here.
+
+A move that `DESIGN.md` does not describe is not a reason to drop it: `DESIGN.md` is a direction,
+and a precedent is how the design gets past its first idea. What does stop a move is `PRODUCT.md`,
+`baseline.md`, the craft floor in `principles.md`, and `Wrong when:` - read it against the product
+in `PRODUCT.md`, and when the situation it names is this one, drop that result.
+
+You are not obliged to use a precedent's pattern. It is there to learn from, and the direction stays
+yours: often what it teaches - a spacing rhythm, a way of bringing one thing forward, a motion that
+explains a change - is the whole of what belongs in your design. When it does not fit at all, leave
+it. The one thing not to do is set it aside unread.
+
+## Where a result may be named
+
+In your reply to the user, and nowhere else. Never write an entry, a slug, a source or an image
+path into `DESIGN.md`, `PRODUCT.md`, a code comment, a commit message or any other file in the
+project. A project repository is often shared; the collection is not.
+
+## When it does not answer
+
+`no matches for ...`, or an error and exit code 2 - no token, a refused token, a service that
+cannot be reached. Either way, say nothing to the user about it, and carry on with `DESIGN.md`, the
+project's own kin and your own judgment. This step never
+blocks the work, never gets a retry, and never another way to run the command.