Skip to content

docs: rewrite the how to name design tokens post around one example - #95

Merged
alexgrozav merged 1 commit into
blog-uxf-803from
post-voice-uxf-880
Nov 19, 2026
Merged

alexgrozav merged 1 commit into
blog-uxf-803from
post-voice-uxf-880

Conversation

@alexgrozav

Copy link
Copy Markdown
Contributor

What changed

The "How to name design tokens" post now reads like the Button docs: a colleague walking you through it, with the reason for every step. It used to read like the Design Tokens page with its headings changed, so it's been rewritten around a single example.

It keeps its first sentence, which answers the question on its own, then opens on three ways names go wrong. From there, one small stylesheet, a theme and a tooltip, is renamed a step at a time: every name gets a path, --blue-2 becomes --color--primary, the tooltip takes its colours from the theme and its arrow gets a group of its own. It ends on the renamed stylesheet, the same path in DTCG, Figma and Styleframe, and how to keep names that way with Stylelint and the page's prompts.

Along the way, it drops the rule IDs in brackets, the sentence that described the post and the tables copied from the Design Tokens page. Every rule is still the page's, and the post links to the section with the detail where a reader would want it. The title, slug, date, author and description stay as they were, and only the post's file changes.

There's room for a story of the author's own in the opening, between the first paragraph and "Think of…", like a stylesheet they once had to rename. The post doesn't make one up.

Checklist

  • The title follows Conventional Commits, as in feat(docs): add the focus guideline.
  • pnpm check-types passes.
  • Docs changes: the pages read well on pnpm dev. (Not run: the post's page builds and prerenders with pnpm build, and its layout didn't change.)
  • Homepage changes: pnpm build, then pnpm lighthouse, still scores 100 in every category. (No homepage changes, and Lighthouse passes.)

Rename one stylesheet, a theme and a tooltip, a step at a time, so each rule comes with its reason and the names improve as the post goes. Drop the rule IDs in brackets, the sentence about the post and the tables copied from the Design Tokens page.

Co-authored-by: multica-agent <github@multica.ai>
@alexgrozav
alexgrozav merged commit 90be152 into blog-uxf-803 Nov 19, 2026
4 checks passed
@alexgrozav
alexgrozav deleted the post-voice-uxf-880 branch November 19, 2026 06:42
alexgrozav added a commit that referenced this pull request Nov 19, 2026
…94)

## What changed

opencomponents.dev gets a blog at `/blog`, and its first post is "How to
name design tokens". People search for that question, and the answer is
on the Design Tokens page, spread across a reference. The post walks
through it step by step and sends readers back to the page. Posts aren't
part of the standard, so the MCP server doesn't read them.

The branch brings together three pull requests:

- #92 adds the blog. It's a Nuxt Content collection built like the
changelog, with a listing at `/blog` and a page per post laid out like a
long-form article: a large headline, the standfirst, the author, date
and reading time, then a narrow column of body text. Both headers link
to it after Changelog. Each post has `BlogPosting` structured data, a
place in the sitemap and `llms.txt`, and a Markdown copy at
`/raw/blog/<slug>.md`, served from its source so its tables stay tables.
`pnpm check-seo` now checks all of this. A content check in
`server/lib/blog.test.ts` reads every token name in a post against the
pattern on the Design Tokens page, so the two can't drift apart.
`.github/CONTRIBUTING.md` and `AGENTS.md` describe the blog.
- #93 writes the post. Its first sentence answers the question on its
own. Six steps follow, each with its reason, its rule ID and a link to
the section of the Design Tokens page it comes from, then worked
examples. The Design Tokens page gains one sentence that links to the
post, and nothing else on it changes.
- #95 rewrites the post in the voice of the docs. One example, a theme
and a tooltip, is renamed a step at a time, and each step gives its
reason. Links to the Design Tokens page sit where a reader would want
the detail, in place of a rule ID after every claim. It's shorter, and
only the post's file changes.

Merging this publishes the blog and its first post.

## Checklist

- [x] The title follows [Conventional
Commits](https://www.conventionalcommits.org), as in `feat(docs): add
the focus guideline`.
- [x] `pnpm check-types` passes. (Run on each part, #92 and #93, along
with `pnpm test`, `pnpm check-reference`, `pnpm build`, `pnpm
check-seo`, `pnpm build:mcp` and `pnpm check-mcp`.)
- [x] Docs changes: the pages read well on `pnpm dev`. (Checked on the
built site, in screenshots of the listing and the post at 375px and
1280px, in light and dark mode.)
- [x] Homepage changes: `pnpm build`, then `pnpm lighthouse`, still
scores 100 in every category. (The homepage gains only the Blog link.
Lighthouse passed on each part.)

---------

Co-authored-by: multica-agent <github@multica.ai>
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.

1 participant