Services

Typography Spacing Review

Typography and spacing review

Executive summary#

The repo has a strong foundation for typography and spacing, but the system is fragmented across shared packages, content/marketing apps, and product/admin apps. Shared token generation exists in packages/config, packages/studio-config, packages/ui, and packages/studio-ui, and several apps already have mature local conventions. However, typography roles, prose defaults, page containers, card density, and compact data-display values are often defined locally instead of through one shared contract.

The highest-impact work is to make existing decisions explicit: define semantic type roles, standardize container and prose rhythm, document product/admin density guidance, and promote repeated raw pixel density values into named tokens. These recommendations are based on the three audit reports in .awao/findings/ and should be implemented incrementally rather than as a broad redesign.

Top cross-repo typography risks#

  1. No shared semantic type scale. The shared audit found that packages/config/tailwind.config.js and packages/studio-config/tailwind.config.js define font families, but not semantic typography roles. Components assemble hierarchy directly with utilities such as text-xs, text-sm, text-xl, and font-medium.
  2. Typography ownership is split across many layers. Content apps define type behavior across apps/docs/styles/main.scss, apps/docs/styles/new-docs.scss, apps/blog/styles/globals.css, MDX CSS, package styles, and route components. Product surfaces similarly split type across apps/studio/styles/typography.scss, shadcn primitives, legacy packages/studio-ui modules, and inline Tailwind classes.
  3. Shared pattern classes depend on app-level definitions. The shared audit notes that heading-title, heading-section, and heading-subSection are consumed in packages/ui-patterns but were not defined in the scoped shared packages inspected, making shared rendering fragile outside Studio.
  4. Font policy differs by surface. apps/manager/src/globals.css uses Lato, apps/admin/src/globals.css uses Inter/system, apps/studio/pages/_app.tsx injects custom font variables, content apps mix manual custom-font, next/font, and Inter, and shared config uses additional font-family assumptions.
  5. Prose contracts are inconsistent. apps/academy/styles/mdx.css has the strongest long-form prose defaults, while apps/blog/styles/globals.css, apps/design-system/styles/mdx.css, and apps/ui-library/styles/mdx.css rely more on imported styles or code-block-focused rules.
  6. Dense UI text lacks a repo-wide readability contract. Product/admin audits found extensive valid use of text-xs, text-sm, 13px grid/editor sizing, and metadata text, but these values are not consistently named as density decisions.

Top cross-repo spacing and layout risks#

  1. Container and page padding contracts overlap. The shared audit cites multiple conventions: PAGE_SIZE_CLASSES in packages/ui/src/lib/constants.ts, containerClasses in packages/ui-patterns/src/layout.ts, and PageContainer using different padding and max-width behavior.
  2. Spacing tokens exist but direct utilities dominate. Generated CSS exposes --spacing-xs/sm/md/lg/xl, but components frequently use direct Tailwind utilities and arbitrary values instead of semantic spacing tokens.
  3. Off-scale and hard-coded density values are common. Shared constants include heights such as h-[26px], h-[34px], h-[38px], h-[42px], h-[50px], while both shared Tailwind wrappers include padding.content: '21px'.
  4. Card and panel density diverges. packages/saas-ui cards use px-6/py-6, while legacy packages/studio-ui/src/components/Card/Card.module.css uses px-8, py-6, and p-8, creating discontinuity near dense Studio tables and panels.
  5. Table layouts favor no-wrap density. packages/saas-ui tables use whitespace-nowrap; audits note this is useful for dense data but can force horizontal scrolling for long values or multiple row actions in Manager/Admin.
  6. Large-screen readability can exceed comfortable measure. Academy shell tokens expand up to 1200px/1320px; the content audit recommends keeping lesson prose constrained independently to roughly 65–75ch.

Quick wins#

  • Move or define the consumed heading-title, heading-section, and heading-subSection classes in a shared stylesheet or replace them with shared class constants in packages/ui-patterns.
  • Replace or explicitly justify padding.content: '21px' in packages/config/tailwind.config.js and packages/studio-config/tailwind.config.js; the shared audit recommends 20px/p-5 unless the optical offset is intentional.
  • Align Admin and Manager font policy by resolving the mismatch between apps/manager/src/globals.css and apps/admin/src/globals.css.
  • Add visible labels to placeholder-only Admin dialog forms called out in apps/admin/src/routes/tenants/index.tsx.
  • Add page-level headers/descriptions to dense Admin pages such as apps/admin/src/routes/dashboard.tsx, apps/admin/src/routes/tenants/index.tsx, and apps/admin/src/routes/audit-logs.tsx.
  • Ensure apps/ui-library uses consistent next/font options such as display: 'swap' if its font-loading behavior should match apps/academy and apps/design-system.
  • Remove or quarantine stale docs styles after confirming usage, especially apps/docs/styles/Home.module.css and commented scaffolding in apps/docs/styles/main.scss / apps/docs/styles/new-docs.scss.

Larger follow-up opportunities#

  • Create a semantic typography layer. Define roles such as body, label, caption, metadata, page title, section title, subsection title, prose heading, code/detail text, and grid cell text in shared config or CSS.
  • Standardize prose defaults for content apps. Share body width, heading margins, line-height, code-block spacing, image rhythm, table behavior, and caption styling across docs, blog, academy, design-system, and ui-library surfaces.
  • Choose one page container contract. Consolidate max-width tiers, breakpoint padding, and section vertical rhythm across packages/ui, packages/ui-patterns, and app-level page shells.
  • Formalize product/admin density guidance. Document when to use text-xs, text-sm, text-base, p-2, p-6, wrapping, truncation, compact rows, and action menus for tables/forms/cards.
  • Promote Studio compact values into named tokens. Keep fontSize.grid: '13px', Monaco fontSize: 13, and text-[12px] where appropriate, but make them explicit density tokens for grid, code, and metadata contexts.
  • Add radius and elevation semantics. The shared audit found generated radius tokens and direct shadow utilities, but no clear radius/elevation hierarchy for controls, cards, panels, popovers, modals, and overlays.
  • Track arbitrary Tailwind values. A lightweight report could allow Radix/CSS-variable cases while flagging raw pixel widths, heights, and spacing that should become tokens.

Prioritized action plan#

  1. Stabilize shared primitives first. Define shared heading classes or constants used by packages/ui-patterns, decide on padding.content, and document a single container rhythm for shared page primitives.
  2. Write the typography and density contracts. Add a concise shared reference for semantic type roles, product/admin density, text measures, table wrapping/truncation, and card spacing expectations.
  3. Align high-visibility product surfaces. Resolve Manager/Admin font policy, add Admin page hierarchy and form labels, and audit table action overflow before changing lower-level primitives.
  4. Unify content prose behavior. Extract or document shared prose defaults for docs/blog/academy/design-system/ui-library, while preserving stronger existing patterns such as apps/academy/styles/mdx.css and apps/www/styles/pen-tokens.css.
  5. Normalize Studio-specific compact design. Treat apps/studio/styles/typography.scss and apps/studio/styles/grid.scss as the source of truth for Studio density, then align legacy packages/studio-ui title/card spacing with that model.
  6. Add ongoing drift checks. Introduce a lightweight arbitrary-value and token-usage report for shared packages and app styles so new raw pixel spacing/type decisions are reviewed deliberately.

Evidence base#

This synthesis is based only on the audit reports at:

  • .awao/findings/review-typography-spacing-shared-system.md
  • .awao/findings/review-typography-spacing-content-apps.md
  • .awao/findings/review-typography-spacing-product-apps.md