Skip to content

docs: say "accessible" in Overview titles and define AX in one sentence - #88

Merged
alexgrozav merged 1 commit into
accessible-titles-uxf-798from
accessible-titles-voice-uxf-851
Nov 17, 2026
Merged

alexgrozav merged 1 commit into
accessible-titles-uxf-798from
accessible-titles-voice-uxf-851

Conversation

@alexgrozav

Copy link
Copy Markdown
Contributor

What changed

Every component Overview now has a seo.title of Accessible <title> - guidelines, like "Accessible Button - guidelines", so search results say "accessible", which is what people type ("accessible button", "accessible combobox"). The page's <h1>, its markdown copy and its llms.txt link keep the component's name, "Button", since the MCP server heads the whole page with it. The 8 Overviews that already had a seo: block get the title inside it.

The 68 layer pages separate their title parts with " - " rather than ": ", as in "Checkbox Group - Developer Experience (DX)", which stays at 42 characters, the longest title.

The Introduction's Agentic experience section (AX layer) now opens with a sentence that defines AX on its own: "Agentic experience (AX) is how well AI agents can read, reason about and build with a component." Its heading and four bullets are unchanged, since the plugin's skills and the MCP server read the headings.

AGENTS.md and .github/CONTRIBUTING.md ("The docs") use the dash example and state the Overview title rule.

This builds on the previous change on this branch, which keeps an Overview's markdown copy and llms.txt link on its title.

Checklist

  • The title follows Conventional Commits, as in feat(docs): add the focus guideline.
  • pnpm check-types passes. So do pnpm check-reference, pnpm test, pnpm check-seo (0 failures) and pnpm check-mcp after both builds.
  • Docs changes: the pages read well on pnpm dev. (Not run. I checked the built <title>, og:title, markdown copies and llms.txt in dist/ instead.)
  • Homepage changes: pnpm build, then pnpm lighthouse, still scores 100 in every category. (No homepage changes.)

Give every component Overview a seo.title of "Accessible <title> - guidelines",
since people search for "accessible button" and an Overview's title is only the
component's name. Separate the layer pages' title parts with " - " rather than
": ", as in "Checkbox Group - Developer Experience (DX)".

Open the Introduction's Agentic experience section with a sentence that
defines AX on its own, and state the Overview title rule in AGENTS.md and
CONTRIBUTING.md.

Co-authored-by: multica-agent <github@multica.ai>
@alexgrozav
alexgrozav merged commit 97f796e into accessible-titles-uxf-798 Nov 17, 2026
5 checks passed
@alexgrozav
alexgrozav deleted the accessible-titles-voice-uxf-851 branch November 17, 2026 10:36
alexgrozav added a commit that referenced this pull request Nov 17, 2026
…nce (#89)

## What changed

The component pages now say what people search for, and the site answers
"what is agentic experience" in one sentence.

- Every component Overview has a search title that says "accessible",
like "Accessible Button - guidelines". Its markdown copy, its `llms.txt`
link and the MCP server's copy keep the component's name (`# Button`),
so agents find the page by name as before. The shared rule is
`rawTitle()` in `server/lib/raw.ts`.
- Every layer page title separates its parts with a dash, like "Button -
User Interface (UI)". `AGENTS.md` and `CONTRIBUTING.md` give the new
pattern and the Overview rule.
- The homepage's `WebSite` JSON-LD has `"alternateName":
"OpenComponents"`, the one-word name people type from the wordmark.
- The Introduction's "Agentic experience" section opens with a sentence
that defines AX: "Agentic experience (AX) is how well AI agents can
read, reason about and build with a component."

This lands #87 and #88.

## Checklist

- [x] The title follows [Conventional
Commits](https://www.conventionalcommits.org), as in `feat(docs): add
the focus guideline`.
- [x] `pnpm check-types` passes.
- [ ] Docs changes: the pages read well on `pnpm dev`. (Not run. The
built pages in `dist/` were read instead: titles, markdown copies and
`llms.txt`.)
- [x] Homepage changes: `pnpm build`, then `pnpm lighthouse`, still
scores 100 in every category.

---------

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