# Typography

## Essence

Foundation text-style token system for every Portfolio text component.

`Typography` defines the shared font family, base size, generated type scale, font weights, and line-height roles consumed by text components.

## Hook

Use when a component needs a text role such as heading, body copy, caption, metadata, or text navigation.

## Internal Rules

- Typography is a foundation token family, not a visual component.
- Text components consume Typography tokens.
- Components should not invent local font sizes, weights, or line heights.
- Font family is Roboto-first with system fallbacks.
- Base size is `--font-size-base: 16px`.
- `1em` equals `16px`.
- Generated size tokens are expressed in `em`.
- Generated type sizes are rounded to whole pixel values before converting to `em`.
- Music Constants define the type-scale ratio.
- Line Heights define text rhythm.
- Letter spacing is `0` unless a future specific token says otherwise.
- Typography does not define text color; color is owned by color tokens and consuming components.

## Current Text Roles

- `Caption`: `0.875em / 14px / regular / line-height 1.2`.
- `Body`: `1em / 16px / regular / line-height 1.5`.
- `Subheading`: `1.125em / 18px / medium / line-height 1.2`.
- `Heading 5`: `1.3125em / 21px / bold / line-height 1.2`.
- `Heading 4`: `1.5em / 24px / bold / line-height 1.2`.
- `Heading 3`: `1.75em / 28px / bold / line-height 1.2`.
- `Heading 2`: `2em / 32px / bold / line-height 1.2`.
- `Heading 1`: `2.3125em / 37px / bold / line-height 1.2`.

## Use When

- Defining or reviewing text components.
- Building `Heading`, `Paragraph`, `Caption`, `Link`, `Menu Item`, or related text-based components.
- Checking whether a new text role should be added.
- Recalculating the type scale.

## Do Not Use When

- A component needs a color choice; use color tokens.
- A component needs spacing, layout, interaction, or focus behavior.
- A component needs arbitrary one-off visual tuning.
- A finished UI needs text content; use a text component.

## Edge Cases

- If a new text role is needed, define it here before using it in components.
- If Music Constants change, recalculate Typography tokens as a set.
- If Line Heights change, review all text components that consume Typography tokens.
- Avoid viewport-based font scaling.
- Avoid using heading-size tokens inside compact controls unless the component essence explicitly allows it.

## Accessibility Notes

- Body text should preserve readable size and line-height.
- Heading levels should use semantic `Heading` component behavior, not just visual tokens.
- Typography scale still needs layout checks for wrapping and readability.
- Color contrast is checked through consuming text components and color tokens.

## Related Components And Patterns

- `Heading`: consumes Heading typography roles.
- `Paragraph`: consumes Body typography.
- `Caption`: consumes Caption typography.
- `Link`: consumes Body typography for text navigation.
- `Menu Item`: consumes Body typography for menu labels.
- `Music Constants`: source math for generated size scale.
- `Line Heights`: source rhythm constants for text roles.

## Code Paths

- `packages/design-system/src/styles/tokens.css`
- `apps/portfolio-site/src/pages/design-system/index.astro`