Skip to content

docs(ranui): add an information-architecture guide - #411

Open
chaxus wants to merge 1 commit into
mainfrom
docs/information-architecture
Open

chaxus wants to merge 1 commit into
mainfrom
docs/information-architecture

Conversation

@chaxus

@chaxus chaxus commented Sep 13, 2026

Copy link
Copy Markdown
Owner

Why

The design section answered three questions — what the tokens are (design system), how to choose between them (design guidelines), how to swap them at runtime (theming) — and none of them answered the one that comes first: what shape should a dense page take at all.

A screen can carry every field the endpoint returns, with filters, status tags and bulk actions, and still leave the reader with no idea what to look at first. Nothing is missing; the order is.

What this adds

A new page, /src/ranui/information-architecture/, in all eight languages. It covers:

  • the three questions that fix a page — primary information, supporting information, next action;
  • why the shape follows the task and not the payload (an array from the endpoint is not a reason for a table; an ID in the route is not a reason for a detail page);
  • a catalogue of 19 expression skeletons, chosen by the question in front of the reader rather than by the business domain;
  • the six pairs that get swapped — timeline vs. steps, kanban vs. filter, calendar vs. timeline, card grid vs. table, graph vs. adjacency list, document vs. field grid;
  • where each kind of information belongs (identity, status, attributes, relationships, changes, evidence, actions, feedback) and where it must not end up;
  • reading order, density, and how to keep task context.

A "what ranui gives you at this layer" section written for this library, not transplanted: r-section / r-card for bands and repeated entries, r-tabs for peer views of one object, r-disclosure-row for progressive disclosure, r-state-dot always with its label — and the plain statement that ranui ships no table, tree, calendar, kanban or timeline, so building one means building it out of the tokens rather than a second visual system.

DESIGN.md §12 carries the same rules for agents. It sits one level above §11 (Composition): §11 arranges a page whose shape is already settled, §12 settles it.

Adapted from alswl's page-organisation guide from Ant Design Pro to ranui.

Drive-by fix: CJK emphasis rendered as literal underscores

Verifying the new page in a browser turned up an existing bug. _emphasis_ does not parse when a delimiter touches a CJK letter, so it reached the reader as literal underscores — ライト_と_ダーク, _전부_를, トークンが_何か_. 24 spans across 10 Japanese and Korean pages were affected.

They become **, which is what the Chinese pages already used for exactly this reason. Only spans that genuinely fail CommonMark's flanking rules were rewritten — correctly rendering _em_ spans (_왜_, _그 폭으로 크기를 바꾸는_) are untouched, and code spans, fenced blocks and link targets were masked out of the rewrite. list_file,read_file in cn/src/article/ai is an identifier, not emphasis, and was left alone.

Verification

  • check:langs — 8 languages, 237 labels, all pages present and structurally matched
  • build — 1401 pages
  • verify — links, anchors, canonicals, assets and sitemap all consistent
  • tsc --noEmit and vitest run pass
  • Full rescan of the rendered site: no literal emphasis underscores left
  • Rendered check in a real browser at 1280px: no page-level horizontal overflow; wide tables scroll inside their own .table-wrap, as on the sibling pages

🤖 Generated with Claude Code

https://claude.ai/code/session_01Cv5oe1ZXN73zVuGWFxNk2V

The design section answered what the tokens are (design system), how to
choose between them (design guidelines) and how to swap them at runtime
(theming) — but nothing answered the question that comes before all three:
what shape should a dense page take at all. A screen can carry every field
the endpoint returns, with filters, status tags and bulk actions, and still
leave the reader with no idea what to look at first. Nothing is missing;
the order is.

New page at /src/ranui/information-architecture/ in all eight languages:
the three questions that fix a page (primary information, supporting
information, next action), why the shape follows the task rather than the
payload, a catalogue of 19 expression skeletons chosen by the question in
front of the reader, the six pairs that get swapped (timeline vs. steps,
kanban vs. filter, calendar vs. timeline, card grid vs. table, graph vs.
adjacency list, document vs. field grid), where each kind of information
belongs, reading order, density, and how to keep task context.

The "what ranui gives you at this layer" section is written for this
library rather than transplanted: r-section/r-card for bands and entries,
r-tabs for peer views of one object, r-disclosure-row for progressive
disclosure, r-state-dot with its label — and the plain statement that ranui
ships no table, tree, calendar, kanban or timeline, so building one means
building it out of the tokens instead of a second visual system.

The agent-facing source gets the same rules as DESIGN.md §12, which sits one
level above §11 (Composition): §11 arranges a page whose shape is already
settled, §12 settles it.

Adapted from alswl's page-organisation guide
(https://github.com/alswl/guides/blob/master/fe-page-guide-antd.md) from
Ant Design Pro to ranui.

Also fixes a rendering bug the new page surfaced: `_emphasis_` does not
parse when a delimiter touches a CJK letter, so it reached the page as
literal underscores. 24 spans across 10 Japanese and Korean pages rendered
as `_と_`, `_전부_`, `_無効_`. They become `**` — which is what the Chinese
pages already used for exactly this reason. Only the spans that genuinely
fail CommonMark's flanking rules were rewritten; correctly rendering `_em_`
spans are untouched.

Verified: 1401 pages build, links/anchors/canonicals/sitemap verify clean,
check:langs passes for all eight languages, and a full rescan of the
rendered site finds no literal emphasis underscores left.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cv5oe1ZXN73zVuGWFxNk2V
@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying ran with  Cloudflare Pages  Cloudflare Pages

Latest commit: c57fd6e
Status: ✅  Deploy successful!
Preview URL: https://89f79cce.ran-4ty.pages.dev
Branch Preview URL: https://docs-information-architectur.ran-4ty.pages.dev

View logs

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