Skip to content

feat: add a blog, with "How to name design tokens" as its first post - #94

Merged
alexgrozav merged 9 commits into
mainfrom
blog-uxf-803
Nov 19, 2026
Merged

alexgrozav merged 9 commits into
mainfrom
blog-uxf-803

Conversation

@alexgrozav

@alexgrozav alexgrozav commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

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:

  • feat: add the blog, its pages and its header links #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.
  • feat(docs): write the how to name design tokens post #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.
  • docs: rewrite the how to name design tokens post around one example #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

  • The title follows Conventional Commits, as in feat(docs): add the focus guideline.
  • pnpm check-types passes. (Run on each part, feat: add the blog, its pages and its header links #92 and feat(docs): write the how to name design tokens post #93, along with pnpm test, pnpm check-reference, pnpm build, pnpm check-seo, pnpm build:mcp and pnpm check-mcp.)
  • 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.)
  • 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.)

alexgrozav and others added 5 commits November 18, 2026 15:53
The blog follows the changelog: a `blog` collection of one post per file
in content/blog/, a listing at /blog and a page per post, both prerendered
in the Docus shell, and a "Blog" link after Changelog in both headers.

Each post writes its own head tags and a BlogPosting, rather than the
Article Docus's useSeo() would add, and has a markdown copy at
/raw/blog/<slug>.md, served from its source with a canonical Link header.
The sitemap, llms.txt and check-seo cover the blog, and a content gate
checks every token name in a post against the Design Tokens page.

The first post is a stub, which its writer replaces.

Co-authored-by: multica-agent <github@multica.ai>
Replace the stub with the post: six steps, each with its reason, its rule ID and a link to the Design Tokens section it comes from, then worked examples and how to check names. The Design Tokens page links to it under its intro.

Co-authored-by: multica-agent <github@multica.ai>
Co-authored-by: multica-agent <github@multica.ai>
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://blog-uxf-803.opencomponents.dev, https://blog-uxf-803-opencomponents.blue-water-0397.workers.dev (commit 7a2e1c0)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Cancelled 🚫

View logs ↗
23d5d9f 2026-11-19T07:05:21.268Z View logs ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://6e5ccdb9.opencomponents.dev, https://6e5ccdb9-opencomponents.blue-water-0397.workers.dev 7a2e1c0 2026-11-19T07:00:57.799Z Visit the dashboard ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://2084fb25.opencomponents.dev, https://2084fb25-opencomponents.blue-water-0397.workers.dev 90be152 2026-11-19T06:51:02.888Z Visit the dashboard ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://74ff0738.opencomponents.dev, https://74ff0738-opencomponents.blue-water-0397.workers.dev 09d76ea 2026-11-18T14:45:12.117Z Visit the dashboard ↗

@alexgrozav
alexgrozav marked this pull request as ready for review November 18, 2026 14:53
@alexgrozav
alexgrozav marked this pull request as draft November 19, 2026 06:21
alexgrozav and others added 2 commits November 19, 2026 08:36
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 marked this pull request as ready for review November 19, 2026 06:49
alexgrozav and others added 2 commits November 19, 2026 08:58
Both headers, and the docs header's menu below 768px, now list the blog first,
then the changelog and the docs. A test keeps the homepage's links and
docsTheme.headerLinks in that order.

Refs UXF-803

Co-authored-by: multica-agent <github@multica.ai>
Clarified the naming convention for design tokens and explained the use of token paths in CSS.
@alexgrozav
alexgrozav merged commit 792082e into main Nov 19, 2026
3 checks passed
@alexgrozav
alexgrozav deleted the blog-uxf-803 branch November 19, 2026 07:05
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