Start by naming the target: official React-oriented shadcn/ui, a framework port such as shadcn/vue, or a third-party distribution. These projects may share visual conventions while using different documentation, installation routes, source files, and update ownership. A typography instruction copied from one target is not automatically valid for another.

For official shadcn/ui, the useful architectural fact is that the component code is open and becomes part of the application. That makes local customization possible, but it also means a copied Button, Table, or Dialog can accumulate typography decisions that no longer follow the theme. Record the exact distribution and component source before deciding where a change belongs.

• Font assets and loading | Owns: font files or provider references, available styles and weights, subsets, fallback stack, and loading policy. Change here when a file, supported weight, or fallback behavior changes. Verify network failure and delayed loading.
• Tailwind or CSS theme | Owns: reusable family aliases, size values, line heights, tracking values, and any theme variables consumed across the application. Change here when the same value should reach many consumers.
• Semantic typography roles | Owns: the mapping from purpose to theme values, such as body, heading, label, metric, identifier, and code. Change here when product meaning changes without changing every component separately.
• Reusable component interface | Owns: repeated markup and constraints that belong to a component, such as a heading hierarchy, a numeric metric treatment, or wrapping behavior inside a button. It should consume roles rather than restate raw families and sizes.
• Written design guidance | Owns: rationale, permitted combinations, exceptions, and examples. DESIGN.md can tell a developer or coding agent when to use a role, but the runtime theme and component code must enforce the rendered result.

Use the highest layer that accurately represents the decision. A new approved fallback belongs with font delivery. A revised body family belongs in the theme. A distinction between body copy and validation text belongs in the semantic role map. A one-line button constraint belongs in the Button implementation. An instruction to reserve mono for code and identifiers belongs in written guidance and should point to a real role.

1. 1

   Approve the available font assets

   List each family, style, and weight the project is allowed to request. A declared weight without a corresponding asset may trigger synthesis or an unexpected fallback, so the inventory is part of the contract.

2. 2

   Choose the loading policy

   Record where the files come from, how they are declared, the fallback stack, and the chosen font-display behavior. Loading is observable behavior, not a theme detail.

3. 3

   Map assets into the theme

   Give the approved families and scale values stable theme names. Consumers should depend on these names instead of repeating literal font stacks and measurements.

4. 4

   Assign semantic roles

   Map heading, body, navigation, control, label, validation, metric, identifier, and code roles to theme values. State whether a role permits more than one weight.

5. 5

   Consume roles in component code

   Inspect copied and generated component files for literal families, sizes, tracking values, line heights, and weights. Keep a local value only when the component has a documented reason to own it.

6. 6

   Verify rendered surfaces

   Test representative content, constrained dimensions, interactive states, fallback rendering, and user text overrides. Store the observation with the decision rather than relying on a visual memory of the preview.

For every generated, copied, or registry-delivered artifact, record two owners: the source that produced it and the person or team responsible for later local changes. Open code gives the project control. It does not keep derivatives synchronized after local edits.

Ambient Sage is a bounded example of the chain, not a recommendation for every shadcn product. Its public kit assigns Plus Jakarta Sans to heading and body roles at weights 400, 500, 600, and 700. JetBrains Mono supplies the mono role at weights 400, 500, and 700. The published typography scale is compact-product.

• Source decision: Plus Jakarta Sans serves heading and body roles; JetBrains Mono serves the mono role.
• Permitted weights: 400, 500, 600, and 700 for Plus Jakarta Sans; 400, 500, and 700 for JetBrains Mono.
• Scale intent: compact-product, which should be checked on dense controls and product surfaces rather than inferred from a marketing headline.
• Delivery artifacts: the public page exposes DESIGN.md, Tailwind v3 and v4 exports, CSS variables, and a shadcn registry export.
• Runtime responsibility: the project still has to load the fonts, connect exported values to its components, and test its own content and layouts.

The useful move is to trace one role. Take a changing account balance. The approved asset list establishes which font and weights exist. The theme exposes the chosen family. A metric role can add the intended weight and numeric behavior. A reusable metric component consumes that role. The dashboard then proves whether digits align, currency symbols fit, and values remain readable when they change.

A useful contract is short enough to inspect and precise enough to reject an accidental override. At minimum, record the following decisions.

• Target distribution and version context: official shadcn/ui, a framework port, or a named third-party distribution.
• Permitted families, styles, weights, subsets, and fallback stacks.
• Font source, loading mechanism, and font-display policy.
• Theme names for families, sizes, line heights, tracking, and weights.
• Semantic roles and the values each role may consume.
• The boundary between shared theme values and component-owned exceptions.
• Numeric requirements for tables, prices, counters, and changing metrics, including whether a font supports the selected numeric form.
• Wrapping, clipping, truncation, and overflow rules for controls and constrained containers.
• Written guidance that explains usage and links each instruction to a runtime role or component.
• Known gaps that still require a designer, developer, content owner, or accessibility review.

Do not request a weight merely because a utility class exists. Confirm that the asset inventory supports it. Likewise, do not add tabular numeric behavior to every string. Apply and verify it where changing columns or values need stable digit widths, and test the actual font and browser combination.

A typography review needs representative content and explicit failure conditions. Copy the record below and replace the sample values with the product's real strings, dimensions, and states.

Role | Surface | Representative content | Dimensions | State | Expected behavior | Fallback check | Observed result | Evidence | Disposition
Heading | Dialog title | Change transfer limit | 320 px container | Open | Wraps without collision or clipping | Same hierarchy and usable layout | [record] | [screenshot or issue] | pass/fix
Body | Help copy | Once your bank is connected... | 320 px container | Default | Comfortable line length; no horizontal overflow | Reflow remains stable | [record] | [evidence] | pass/fix
Navigation | Sidebar item | Scheduled transfers | Narrow sidebar | Active and focus | Label remains distinguishable; focus treatment is intact | No clipped label | [record] | [evidence] | pass/fix
Control | Primary button | Save preferences | Minimum supported width | Default, hover, focus, disabled | Label fits or follows documented wrap rule | No unreadable substitution | [record] | [evidence] | pass/fix
Label | Form field | Minimum payout amount | Narrow form | Default and error | Label and input association remain visually clear | No overlap | [record] | [evidence] | pass/fix
Validation | Field error | Enter an amount between 50 and 10,000 | Narrow form | Invalid | Message wraps and remains adjacent to its field | No clipping | [record] | [evidence] | pass/fix
Table | Amount column | 1,211.29 USD | Narrow and wide table | Sorted and loading | Values scan consistently; overflow rule is visible | Digits remain legible | [record] | [evidence] | pass/fix
Metric | Live balance | 418.2K Visitors | Card at minimum width | Value changes | Digits do not cause unintended layout jumps | Replacement font is acceptable | [record] | [evidence] | pass/fix
Identifier | Reference ID | INV-2026-00841 | Card and table cell | Copyable | Similar characters remain distinguishable | No width break | [record] | [evidence] | pass/fix
Code | Command | npx shadcn add [registry item] | Docs callout | Wrapped and copied | Code remains selectable and contained | Mono fallback is readable | [record] | [evidence] | pass/fix

• Headings: page titles, card titles, dialog titles, and empty-state headings.
• Body copy: short instructions, long help text, and content with links or inline emphasis.
• Navigation: compact sidebars, breadcrumbs, tabs, menus, and active states.
• Controls: buttons, inputs, selects, toggles, date fields, and destructive actions.
• Messages: validation errors, alerts, toasts, disabled explanations, and loading text.
• Data: tables, prices, percentages, dates, account balances, charts, and rapidly changing metrics.
• Technical content: code, keyboard labels, file paths, identifiers, and strings containing similar glyphs.
• Localization pressure: long labels, mixed case, punctuation, accented characters, and any shipped locale the product supports.

• Narrow the container until the documented minimum width. Record the first wrap, clip, overlap, or overflow failure.
• Increase browser zoom and repeat the critical navigation, form, dialog, and table tasks.
• Apply custom text-spacing overrides. Observe whether content or controls clip, overlap, disappear, or lose meaning.
• Delay the web font and inspect the fallback render before the preferred font arrives.
• Block the font request and complete the same task with the fallback stack.
• Use long labels and validation messages instead of placeholder copy.
• Change metric values across narrow and wide digits, currency symbols, negative values, decimals, and percentages.
• Inspect default, hover, focus, disabled, invalid, loading, expanded, and selected states where typography or available space changes.
• Compare light and dark presentation where the theme supports both, while keeping typography and contrast conclusions separate.

These checks produce bounded observations. Passing them does not establish complete accessibility or responsive correctness. A typography worksheet cannot verify keyboard behavior, screen-reader output, focus order, product logic, or every viewport and content combination. Contrast also requires its own evidence.

A controlled change reveals whether the authority map is real. Pick one reversible typography decision with several known consumers, such as the body role's weight or the mono role used for identifiers. Do not change component files at the same time.

1. 1

   Record the baseline

   Capture the authoritative value, expected consumers, representative rendered surfaces, and unrelated surfaces that should remain unchanged.

2. 2

   Change one authoritative decision

   Edit only the layer that claims ownership. Keep the old value and the reason for the test in the decision record.

3. 3

   Confirm delivery

   Verify that the expected theme variable, role, or generated artifact contains the new value. This distinguishes a delivery failure from a rendering failure.

4. 4

   Inspect intended consumers

   Check every named surface and state. Record which consumers changed, which did not, and whether any local override blocked the update.

5. 5

   Inspect unrelated surfaces

   Look for unintended drift. A body-role change should not silently alter code, metrics, or component-specific labels unless the authority map says they inherit that role.

6. 6

   Set the disposition

   Accept the change, fix a named mapping, document a justified component exception, or restore the prior authoritative value through the normal controlled workflow. Keep the evidence with the record.

Decision: [one typography choice]
Target: [official shadcn/ui, port, or distribution]
Authoritative layer: [assets, loading, theme, role, component, guidance]
Source artifact: [name and version or capture date]
Local owner: [person or team]
Approved value: [family, weight, size, line height, tracking, numeric feature, or rule]
Expected consumers: [components and surfaces]
Excluded consumers: [surfaces that must not change]
Fallback behavior: [expected substitution and loading behavior]
Test content: [real representative strings]
Test dimensions and states: [record]
Observed failures: [wrapping, clipping, overflow, shift, substitution, or none observed]
Evidence: [screenshot, issue, test output, or review note]
Disposition: [accept, fix mapping, document exception, or restore]
Known limits: [what this test did not establish]

The next practical step is to choose one rendered surface, trace its text back through component, semantic role, theme, loading declaration, and font asset, then run the controlled-change test. If the trace breaks, fix that ownership gap before adjusting more typography values.

• Introduction - shadcn/ui: The official introduction presents shadcn/ui as open component code built around composition and distribution, and links to theming, Typeset, and typography resources.
• The Foundation for your Design System - shadcn/ui: The official showcase provides representative navigation, forms, controls, dialogs, tables, financial values, dashboards, and chat content for rendered typography checks.
• Ambient Sage Design Kit: The public kit documents its typography roles and exports, including Plus Jakarta Sans, JetBrains Mono, DESIGN.md, Tailwind formats, and a shadcn registry artifact.
• font-display CSS at-rule descriptor: MDN documents the font-display descriptor used to control how a downloadable font is shown while it loads or when it is unavailable.
• font-variant-numeric CSS property: MDN documents font-variant-numeric and the numeric forms that can be selected for text such as metrics, prices, and tables.
• Best practices for fonts: The guide treats font loading, delivery, file formats, subsetting, fallback rendering, and the number of web fonts as separate implementation decisions.
• font-family - Tailwind CSS: Tailwind documents font-family utilities and connects typography configuration with theme variables and custom styles.
• Introduction - Shadcn Studio: The documentation describes copied or installed shadcn components as locally customizable open code rather than an opaque conventional package.