Workbench interface primitives#

Forge's artifact pages should feel like objects laid out on the same smith's bench, not unrelated dashboards. The shared implementation lives in packages/web/src/components/workshop/ArtifactWorkbench.tsx with its styles in artifact-workbench.css.

Composition#

ArtifactMasthead introduces one artifact with an eyebrow, seal, title, description, immutable coordinates, and a small action group.
ArtifactWorkbench provides a fluid main surface and optional sticky rail. The rail becomes a two-column shelf below 900 px and a single column below 640 px.
ArtifactSurface presents paper, inset, or dark material without inventing a new card language per feature.
ArtifactRailSection groups navigation, history, metadata, or secondary controls. Primary mutations do not belong in the rail.
ArtifactStamp communicates provenance or semantic state. Color never carries meaning alone; every stamp needs readable text.
ArtifactMetric is for a small set of directly comparable coordinates, not arbitrary prose.

Repository code, Wiki, Gists, pull requests, transcripts, commits, Sites, and Actions may compose these primitives differently. They should retain their domain-specific information architecture while sharing material, type, spacing, focus, and responsive behavior.

Interaction rules#

One page owns one h1; surfaces and rail sections begin at h2.
Buttons that reveal content expose aria-expanded; menus close on Escape and outside interaction.
Modal sheets and mobile drawers have a labelled close control, close on Escape, and use a real button for the backdrop.
Icon-only controls require an accessible name. Decorative forge imagery is aria-hidden or has intentionally useful alt text.
Focus uses --forge-focus and remains visible on every material. Hover is never the only way to reveal required information.
Motion respects prefers-reduced-motion; layout and reading order do not depend on animation.
Sticky rails must return to document flow at narrow widths so they cannot overlap content or browser chrome.

Review checklist#

Before shipping a workbench page, inspect light and dark themes at desktop and 390 px widths, tab through every control, close every overlay with Escape, and verify loading, empty, error, and long-content states. A shared visual language does not excuse clipped labels, horizontal page overflow, duplicate headings, or controls whose state is only visual.

Composition#

ArtifactMasthead introduces one artifact with an eyebrow, seal, title, description, immutable coordinates, and a small action group.

ArtifactWorkbench provides a fluid main surface and optional sticky rail. The rail becomes a two-column shelf below 900 px and a single column below 640 px.

ArtifactSurface presents paper, inset, or dark material without inventing a new card language per feature.

ArtifactRailSection groups navigation, history, metadata, or secondary controls. Primary mutations do not belong in the rail.

ArtifactStamp communicates provenance or semantic state. Color never carries meaning alone; every stamp needs readable text.

ArtifactMetric is for a small set of directly comparable coordinates, not arbitrary prose.

Interaction rules#

One page owns one h1; surfaces and rail sections begin at h2.

Buttons that reveal content expose aria-expanded; menus close on Escape and outside interaction.

Modal sheets and mobile drawers have a labelled close control, close on Escape, and use a real button for the backdrop.

Icon-only controls require an accessible name. Decorative forge imagery is aria-hidden or has intentionally useful alt text.

Focus uses --forge-focus and remains visible on every material. Hover is never the only way to reveal required information.

Motion respects prefers-reduced-motion; layout and reading order do not depend on animation.

Sticky rails must return to document flow at narrow widths so they cannot overlap content or browser chrome.

Review checklist#