feat(skills): add PRD/structure/design refs, sharpen ui-review - #27
Open
JiangWeixian wants to merge 7 commits into
Open
feat(skills): add PRD/structure/design refs, sharpen ui-review#27JiangWeixian wants to merge 7 commits into
JiangWeixian wants to merge 7 commits into
Conversation
Feature-level flow diagrams and product-level site maps/journeys were sharing FEATURES.md with no boundary, causing overlap. Add structure.md as the detail template for PRODUCT.md's Structure layer, and extend features.md with Flow, Glossary, and document-level Out of Scope sections, based on a real FEATURES.md case study.
Site Map guidance previously left the format open (tree/table/list) with no clear rule. Depth alone was tempting people toward mermaid for deep hierarchies that a plain text tree already handles fine. Add the real criterion: use a text tree by default; switch to a mermaid graph only when a page has more than one parent and the map is no longer a tree.
…with IA Adopt the feat/designmd plan: add references/designmd.md for writing/editing/auditing DESIGN.md against Google Labs' design.md alpha spec (live-fetch required reading, facts-source gate, lint gate, no-visual-surface gate), verified against the real spec before writing. Wire DESIGN.md into SKILL.md's routing, self-check, and common mistakes. Also align structure.md's terminology with Garrett's Elements of User Experience: name Information Architecture explicitly as what Site Map produces, and note Skeleton as the still-undocumented layer that presents this structure on screen.
Required before the PR — the branch touches skills/write-docs content (structure.md, designmd.md, features.md, product.md, SKILL.md) with no prior changeset covering it.
Add first-class PRD.md support: a self-contained initiative-spec reference modeled directly on a real PRD from this org's own practice (docs/product/repository-branch-mention-prd.md), not a generic template. Covers Background, Product Goals, Users & Scenarios, Product Principles, Scope, User Flows, Interaction Rules, Display Rules, States & Exception Handling, Compatibility Requirements, Acceptance Criteria, and Success Determination (qualitative by default, no invented metrics). Every section stands alone without requiring PRODUCT.md or FEATURES.md to exist. Wire PRD.md into SKILL.md's routing, fact-scanning, self-check, and common mistakes.
…rsistence Real-world use surfaced three gaps in implementation-fidelity.md's Figma comparison: values were being eyeballed from screenshots instead of read exactly, the review checklist was prose that got skimmed rather than enumerated, and coverage verdicts could hide a real gap behind a hedge word like "mostly consistent" with no disclosed delta. Add Reading Exact Values (prefer Figma Dev Mode/API/MCP over visual estimation, label estimates when that's all that's available), Coverage: Enumerate Before Comparing (explicit checklist with a compared/total ratio and named skips), and require coverage rows as a design-vs-live comparison table instead of a verdict sentence, so a claim of "match" or "difference" always has both raw values next to it. Wire report persistence to .ui-review/reports/ and fix Regression mode, which previously had no baseline to diff against. Verified against a real run: a Codex session using this skill with the superfigma MCP against a live page produced a report that used exact Figma token values, an explicit 10/12 coverage enumeration with named skips, and correctly flagged an intentional design deviation instead of treating it as a bug.
…idelity work Covers the two commits since the last changeset: prdmd.md (PRD.md support) and the ui-review Figma fidelity sharpening.
JiangWeixian
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
references/structure.mdto the write-docs skill forPRODUCT.md's Structure layer — site maps, cross-feature journeys, and an explicit boundary againstFEATURES.md's per-feature Flow.DESIGN.mdsupport via a newreferences/designmd.md, following the Google Labsdesign.mdalpha spec (verified against the live spec before writing).PRD.mdsupport via a newreferences/prdmd.md— a self-contained, initiative-scoped spec modeled on a real-world PRD, distinct fromPRODUCT.md's living five-layer model.references/features.mdwith an optional per-feature Flow subsection, a Glossary section, and a document-level Out of Scope section, based on a real-worldFEATURES.mdcase study.Changes
write-docs skill
skills/write-docs/references/structure.md(new) — Reader Questions, Site Map (text tree vs. mermaid graph guidance), Flow template, Evidence Rules, boundary vs.FEATURES.md, Self-Check. Aligned terminology with Jesse James Garrett's Elements of User Experience (Site Map = Information Architecture's output).skills/write-docs/references/designmd.md(new) — required-reading live-fetch of the alpha spec,<designmd_facts_source>gate (no invented tokens), lint gate (npx @google/design.md lintmust exit 0), no-visual-surface gate, Recommended Shape, Front Matter, Components whitelist, Self-Check.skills/write-docs/references/prdmd.md(new) — modeled directly on a real PRD from this org's own practice, not a generic template. Covers Background, Product Goals, Users & Scenarios, Product Principles, Scope, User Flows, Interaction Rules, Display Rules, States & Exception Handling, Compatibility Requirements, Acceptance Criteria, and qualitative-by-default Success Determination. Every section stands alone without requiringPRODUCT.md/FEATURES.mdto exist.skills/write-docs/references/features.md— optional### Flowsubsection (scoped to one feature's internal steps), optional## Glossary, document-level## Out of Scope.skills/write-docs/references/product.md— link Structure section tostructure.mdfor detailed guidance.skills/write-docs/SKILL.md— routeDESIGN.md,PRD.md, andstructure.mdthrough required reading, file organization, canonical filenames, self-check, and common mistakes.ui-review skill
skills/ui-review/references/implementation-fidelity.md— add "Reading Exact Values" (prefer Figma Dev Mode/API/MCP over screenshot eyeballing; label visual estimates when exact extraction isn't available), "Coverage: Enumerate Before Comparing" (explicit design-reference checklist with a<compared>/<total>ratio and named skips), and require coverage verdicts as a design-vs-live comparison table instead of a prose verdict, so a claim like "mostly consistent" can't hide an undisclosed delta.skills/ui-review/SKILL.md— persist each report to.ui-review/reports/<date>-<scope>.md; wire Regression mode to look up and diff against the most recent matching report instead of silently skipping the comparison when no baseline exists.Changesets
.changeset/structure-designmd-references.md— minor bump forsupermario..changeset/prdmd-and-ui-review-fidelity.md— minor bump forsupermario.Test Plan
designmd.md's claims about the Google Labsdesign.mdalpha spec against the live spec (docs/spec.md,README.md) rather than from memory.designmd.md: file line count within target range, all 6SKILL.mdrouting locations present (grep -n "DESIGN" SKILL.md), opening pattern matchesreadme.md's shape, no spec duplication, live-fetch URLs present, both gates present.prdmd.mdmodeled on and cross-checked against a real PRD example (docs/product/repository-branch-mention-prd.md) rather than a generic template; verified all 11SKILL.mdPRD wiring points viagrep -n "PRD" SKILL.md.superfigmaMCP against a live page produced a report using exact Figma token values, an explicit 10/12 coverage enumeration with named skips, and correctly flagged an intentional design deviation instead of treating it as a bug.pnpm changeset statusconfirmssupermariois flagged for a minor bump with no other packages affected.