Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
mahanti wants to merge 2 commits into
base: codex/design-system-component-pages
Choose a base branch
from
Draft

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
37ca6f6
feat(design-system): add BlockUI logic and grammar reference
mahanti Sep 10, 2026
e06c7e5
fix(design-system): show grammar rules in flat tables
mahanti Sep 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions desktop-next/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,15 @@ Direct links and refreshes work with the same SPA fallback as the rest of the
site; unknown component IDs have a recovery link. Theme and density preferences
are shared.

## Logic & grammar

`/design/grammar` is a BlockUI reference under System. Every topic is displayed
as a flat table of selection rules and usage boundaries, with links to the
verified upstream snapshot. Tables scroll horizontally on narrow screens. Topic links support direct loading and refresh. It covers foundations,
component contracts, applet composition, and generation constraints; the final
topic records differences from Buzz's active token contract and upstream gaps.
Source links require Block access, but the page has no private runtime dependency.

## Appearance

The navigation contains independent theme and Normal / Compact controls. Density
Expand Down
4 changes: 4 additions & 0 deletions desktop-next/TESTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,3 +55,7 @@ nested navigation links, unknown-ID recovery, input and keyboard interactions,
portal density, refresh, and appearance preferences. Representative pages are
checked at 390/884/1440 in both densities and audited in both themes, with distinct
per-component screenshots.

Grammar-page coverage checks sidebar navigation, always-visible tables,
keyboard topic links, hash links across reloads, all 19 typography rows,
source-link destinations, responsive tables, and accessibility in both themes.
6 changes: 6 additions & 0 deletions desktop-next/src/app/routes/design/grammar.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
import { createFileRoute } from "@tanstack/react-router";
import { GrammarPage } from "@/features/design-system/ui/GrammarPage";

export const Route = createFileRoute("/design/grammar")({
component: GrammarPage,
});
23 changes: 23 additions & 0 deletions desktop-next/src/features/design-system/catalog/catalog.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,29 @@
min-width: 0;
max-width: 100%;
}
.grammar-section {
scroll-margin-top: var(--space-panel-inset);
}
.grammar-section:target {
outline: 2px solid var(--ring-focus);
outline-offset: 4px;
}
.grammar-table {
table-layout: fixed;
}
.grammar-table:focus-visible {
outline: 2px solid var(--ring-focus);
outline-offset: -2px;
}
.grammar-table th,
.grammar-table td {
white-space: normal;
overflow-wrap: anywhere;
vertical-align: top;
}
.grammar-table th:first-child {
width: 24%;
}
.component-page > header h1:focus {
outline: none;
}
Expand Down
Loading
Loading