Docs: tables that read on a phone, and settings as definition lists - #226

Summary

Tables across the docs squeezed into one word per line, wrapped identifiers mid-word, or pushed phones sideways. This restyles every table and turns the ones that are really lists (settings, fields, checks with their fixes) into definition lists. It follows #222, which fixed the import comment. Paired with CoderHelm/coderhelm-platform#311, which converts the self-host guides' list-shaped tables.

What the best docs sites do (Stripe, Vercel, Supabase, Tailwind, Linear, GitHub Docs, Cloudflare, Fly, Railway; checked from their shipped HTML and CSS):

• None uses a sticky first column, and none switches to cards on phones. A table scrolls inside its own box (Vercel sets a 640px min-width on the table, Fly and Linear set min-widths on cells), with an edge fade only while there is more to scroll (Supabase, Fly).
• Headers are quiet: 13 to 14px, weight 600, not uppercase, often on a muted fill (Cloudflare, Railway, Vercel). Headers stay on one line.
• No zebra stripes; GitHub turns them off on purpose. Rows get 1px dividers and no lines between columns, inside one rounded border around the whole table (Cloudflare). Cells are aligned to the top, with about 10 to 12px of vertical padding.
• Code in a key column stays on one line (Supabase). Code in text columns may wrap.
• Parameter and field lists are not tables. Stripe and GitHub stack each one: the name, a muted type, a required badge, then the description.

Changes

• components/table.tsx (new). Every Markdown table renders through it:
  • One focusable scroll box (role=region, so a keyboard can scroll it).
  • Columns are sized from their content. Short keys, and columns that hold only identifiers, stay on one line. Long text gets a minimum width (8, 11 or 15rem, only in tables of three or more columns), so it never squeezes to one word per line.
  • Code in text cells gets break points after / - _ : and before ., so it wraps at a separator and never mid-word. Key columns get none, because Chrome breaks at <wbr> even under nowrap.
• app/global.css:
  • Tables have a muted, one-line header, row hairlines, no column lines, top-aligned cells and 14px text. Code chips wrap with box-decoration-break: clone. A background fade marks the edge that has more to scroll.
  • Definition lists: a list whose items open with a bold term and a hard line break loses its bullets and gets a hairline between items. The italic part (a type, a default, a label such as "Fix:") is muted. It is plain Markdown, so the platform repo's guides read the same on GitHub.
• scripts/lib/manifest-reference.mjs: the plugin manifest reference renders fields as definition lists (name, then the type, "required" and the default, then the description) instead of 13 five-column tables. MDX escaping now leaves inline code alone, so patterns such as ^[a-z0-9_-]{1,40}$ no longer show stray backslashes.
• concepts/skills.mdx (frontmatter fields) and api/errors.mdx (error body fields): converted to the same definition lists.
• e2e/tables.spec.ts (new) runs 13 table-heavy pages at 1440 and 390px, in light and dark. On each page:
  • The page never scrolls sideways.
  • Every table sits in a focusable scroll box, and header cells stay on one line.
  • No identifier in a key column wraps, and no text column is narrower than 110px.
  • Definition lists have no bullets and a hairline between items.
  • Imported pages show no import comment, and their edit link opens the platform file.
• e2e/site.spec.ts: the manifest test looks for the field names in the new lists instead of in table cells.

Every table, and what happened to it

Converted to definition lists:

• Plugin manifest reference: all 13 field tables (generated).
• concepts/skills: the Field, Type, Default, Notes table.
• api/errors: the Field, Type, Description table.
• Self-host guides, in the platform PR:
  • options: At install (6 columns) and After install (4 columns).
  • config-reference: 8 Setting, Type, Default, Notes tables.
  • check-your-install: the doctor's options, Every check (30 rows, now grouped under one heading per group) and the setup-status codes.
  • domains: the status codes.
  • troubleshooting: checks and fixes.
  • updates: the auto-update settings.
  • backups: What holds data.

Kept as tables, restyled. These are true comparisons or short lookup tables:

• Self-host:
  • backups and integrations: Job, When.
  • check-your-install: Step, Checks.
  • config-reference: Variable, From.
  • deliveries: Source, What's recorded.
  • domains: Path, Goes to; the three ways; the DNS records; the providers.
  • github-app: Permissions; GitHub settings.
  • hybrid: all three tables.
  • index: Way, Best for.
  • knowledge-sources: the source matrix.
  • model-providers: Anthropic compared with Bedrock.
  • requirements: Tool, Version, Why.
  • security: From, To, How.
  • sign-in: Setting, Who, Where.
  • updates: File, What.
• Plugins:
  • index: words and pages.
  • layout: paths.
  • outputs: statuses.
  • repos: public compared with private.
  • security: capabilities.
  • settings: types.
  • skills-agents-tools: Field, Meaning; risks.
  • versioning: changes.
• Getting started:
  • first-run: stages.
  • github: permissions.
  • index: parts.
  • reviewer: comments; sections.
• Concepts:
  • agent-permissions: all four tables.
  • agents.
  • connections: 17 servers.
  • data-sources.
  • index.
  • knowledge-sources: all three tables.
  • memories.
  • roles: both tables.
  • skills: Kind, Path; Limits.
  • token-limits: both tables.
  • usage-and-audit.
• API:
  • authentication: all three tables.
  • errors: the codes (Status, code, Meaning, Retry?).
  • index: resources.
  • pagination.
  • rate-limits: headers.
  • versioning.
  • webhooks: both tables. Left as they are, because another branch is editing the webhooks docs.

Two-column tables are already definition-shaped and fit a phone, so they stay tables. The self-host pages for email, sign-in, model providers and security keep their tables; only their styling changes, because other branches are editing those pages.

Platform lock

Pinned at 22548c6e2333 for now. Everything here also works with the current lock: the guides' remaining tables pick up the new table styling. Once CoderHelm/coderhelm-platform#311 merges, npm run platform:bump imports the definition lists. With that bump, add options, config-reference, backups and troubleshooting back to the definition-list e2e test (there is a note at the spot).

Verification

• npm run test:unit: 75 pass. typecheck: OK.
• Build OK, then check:output (88 pages, with the raw-syntax check from Docs: imported pages no longer print their import comment; build fails on raw syntax #222) and check:links (4163 links, none broken) both pass.
• playwright test: 129 pass. This includes the new table suite and the existing 390px no-sideways-scroll tests. The run was against both the pinned lock and the platform PR's commit (PLATFORM_DIR).
• Screenshots at 1440 and 390, light and dark, of backups, options, config-reference, check-your-install, domains, troubleshooting, api/errors, plugins/manifest-reference and concepts/knowledge-sources, before (production) and after. Each one was reviewed. Fixes made from that review:
  • Identifiers in key columns no longer break at <wbr>.
  • File names break before the dot, never after a leading one.
  • The options page has one attribute per line on phones.