Skip to content

feat(design-system): document BlockUI logic and grammar - #7556

Draft
mahanti wants to merge 2 commits into
codex/design-system-component-pagesfrom
codex/design-system-grammar
Draft

feat(design-system): document BlockUI logic and grammar#7556
mahanti wants to merge 2 commits into
codex/design-system-component-pagesfrom
codex/design-system-grammar

Conversation

@mahanti

@mahanti mahanti commented Sep 10, 2026

Copy link
Copy Markdown
Contributor

Adds System → Logic & grammar at /design/grammar, a compact reference for selecting BlockUI tokens and composing supported interfaces. Fifteen always-visible tables cover role resolution, all 19 typography roles, color/emphasis, interaction states, geometry, component contracts, intent and modes, applet slots, visualization selection, palettes, the 12 composition defaults, size/data fallbacks, and generated-response constraints.

Each topic pairs usage with its boundaries and links to a verified upstream snapshot. The page identifies source-specific exceptions, provisional guidance, and differences from Buzz’s active type, font, and density contracts. It summarizes the reference without importing private fonts, assets, implementations, or a runtime service. Source links require Block access. It does not change token values or implement the upstream planner.

Every topic renders as a heading and a flat table, with no collapsible sections. Topic links support keyboard navigation and refresh. Tables scroll horizontally on narrow screens and remain keyboard-accessible. Theme and Normal/Compact density remain shared.

Stack 7: #7522#7523#7525#7533#7535#7537 → this PR. Base: codex/design-system-component-pages. Keep draft.

Validation:

  • Production build, TypeScript, formatting, typography, contrast, token freshness, and all 8 token/schema/renderer checks pass.
  • All 35 Chromium tests passed in the full run. The two grammar tests passed again after the flat-table refinement, including always-visible content, hash navigation, phone-width scrolling accessibility, and both themes and densities.
  • Manual local inspection at desktop and phone widths; automated table visibility, navigation, direct-link, responsive, and light/dark accessibility coverage.
  • Repository-wide just ci passed the earlier checks and desktop tests, then stopped at the unchanged buzz-terminal::lifecycle_tests::default_prog_child_observes_the_login_argv0: the child did not report $0 within 10 seconds. The same failure occurred before this change. Later repository-wide stages were not reached; no terminal or Rust code changed.

Signed-off-by: Arjun Mahanti <arjun@squareup.com>
Signed-off-by: Arjun Mahanti <arjun@squareup.com>
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