Skip to content

docs: add Universal design principles page and Verdicts hero - #50

Open
anahernandez-dev wants to merge 4 commits into
mainfrom
docs/design-guidelines-2026-11-16
Open

anahernandez-dev wants to merge 4 commits into
mainfrom
docs/design-guidelines-2026-11-16

Conversation

@anahernandez-dev

@anahernandez-dev anahernandez-dev commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

What changed

New page: Universal design principles

  • __docs__/universal-design-principles.mdx covers Principles 1–7 and the Guardrail. Each section has a description, an example, what it rules out, and a Big 4 check.
  • It's pinned in the sidebar between Introduction and Foundations (.storybook/preview.tsx → storySort.order).
  • The header image is exported from Figma at 2x (2304×920), matching the other page headers.

Verdicts hero image

  • __docs__/verdicts.mdx is generated, so the image is added in scripts/build-verdicts-page.mjs, and the page was regenerated with pnpm verdicts:page. pnpm verdicts:check passes.

Why

Universal design principles moves from a Google Doc into the guidelines, so designers and the MCP docs tools can use it alongside Foundations, Components and Patterns.

The table column alignment fix that was here moved to its own PR, #51.

Changes since the first review

  • Strategy links removed. They weren't tied to a defined org-level list.
  • Big 4 checks: the user's question is now in quotes so it reads apart from the design check. The intro names the four questions ("What is this?" "Where am I?" "How do I move forward?" "How do I go back?"), taken from the checks.
  • Principle 3 now has two examples: wayfinding in a setup flow, and the student queue.
  • Principles 2 and 5: Rules out reworked so each item is concrete and specific to its principle. Overlaps with Principle 4 are removed.
  • Consistency: every example starts with a user role. "Product" and "part of the product" are used consistently, and Principle 7 no longer uses "error" for things it defines as mistakes.
  • Principle 7 is no longer marked as a draft.

Still to confirm

  • Principle 1: is "Getting there" a real mastery label?
  • Principle 5: "one click from their dashboard" stands in for the real path back to a skipped onboarding step.

Checked

  • pnpm typecheck and pnpm verdicts:check pass.
  • In local Storybook, both pages render, the new page sits in the right sidebar spot, and all in-page anchor links work.
  • Not checked: the a11y addon panel and the syl-dark theme.

🤖 Generated with Claude Code

- Add a Universal design principles page (Principles 1–7 and the
  Guardrail), pinned between Introduction and Foundations
- Add header images to Universal design principles and Verdicts; the
  Verdicts hero is emitted by build-verdicts-page.mjs so the page stays
  in sync with verdicts:check
- Data tables: right-align numeric columns and their labels

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anahernandez-dev
anahernandez-dev requested a review from a team as a code owner November 16, 2026 11:44
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

A new build was pushed to Chromatic! 🚀

https://6a5008743971119020a6233b-xqwkzdzuks.chromatic.com/

Ana Camila Hernandez and others added 2 commits November 16, 2026 15:54
- Remove Strategy links; they weren't tied to a defined org-level list
- Principle 3: use wayfinding and student queue examples
- Principle 5: say what the teacher wants in the example; clarify and
  trim Rules out items
- Quote the user's Big 4 question so it reads apart from the design check
- Clarify Principle 2's "numbers" item, Principle 7's Big 4 check, and
  the Guardrail's student data item

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Principle 2: add Rules out for unranked problems and links that make
  users hunt; drop the item Principle 4 already covers
- Principle 5: say "without extra steps"; rework Rules out around
  skippable setup and clarity over step count; plain-language Big 4 check
- Principle 6: "any part of the product" instead of naming products
- Principle 7: drop the draft note; "Messages" not "Error messages"
  so it matches the principle's own definition of errors
- Use a user-role prefix on every example; drop "in classrooms" and a
  second-person slip in Principle 3; shorten the intro

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anahernandez-dev anahernandez-dev changed the title docs: add Universal design principles page, Verdicts hero, and table alignment fix docs: add Universal design principles page and Verdicts hero Nov 17, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants