# Styling

Match components to your site with Prosefly CSS tokens.

import { Badge, Callout } from "@prosefly/astro-components";

The components ship with fallback styles, but production documentation should
set shared tokens in the site shell. This keeps callouts, cards, tabs, badges,
and file trees aligned with the surrounding typography, colors, and radius.
The built-in token defaults include dark-mode values for
`:root[data-theme='dark']` and for system dark mode when `:root` has no
`data-theme` or uses `data-theme='system'`.

## Recommended Scope

Set tokens on `:root` for a full documentation site. Set them on a layout
wrapper if only one section should use the Prosefly visual system.
Component defaults use low-specificity cascade-layer rules, so normal site CSS
overrides still win.

```css
:root {
  --pf-text-strong: #18181b;
  --pf-text: #3f3f46;
  --pf-text-muted: #71717a;
  --pf-background: #ffffff;
  --pf-surface: #fafafa;
  --pf-accent: #3e7e55;
  --pf-accent-soft: #e4f3e8;
  --pf-accent-contrast: #ffffff;
  --pf-info: #2563eb;
  --pf-info-soft: #dbeafe;
  --pf-info-ink: #1d4ed8;
  --pf-info-contrast: #ffffff;
  --pf-success: #059669;
  --pf-success-soft: #d1fae5;
  --pf-success-ink: #047857;
  --pf-success-contrast: #ffffff;
  --pf-warning: #d97706;
  --pf-warning-soft: #fef3c7;
  --pf-warning-ink: #92400e;
  --pf-warning-contrast: #1c1917;
  --pf-danger: #dc2626;
  --pf-danger-soft: #fee2e2;
  --pf-danger-ink: #b91c1c;
  --pf-danger-contrast: #ffffff;
  --pf-border-subtle: #e4e4e7;
  --pf-border-muted: #d4d4d8;
  --pf-font-sans: ui-sans-serif, system-ui, sans-serif;
  --pf-font-mono: ui-monospace, SFMono-Regular, Menlo, monospace;
  --pf-radius-sm: 0.25rem;
  --pf-radius-md: 0.5rem;
  --pf-radius-lg: 0.75rem;
  --pf-radius-full: 999px;
}
```

## Token Reference

| Token                                                        | Used For                                   |
| ------------------------------------------------------------ | ------------------------------------------ |
| `--pf-text-strong`                                           | Headings, card titles, active labels       |
| `--pf-text`                                                  | Body text                                  |
| `--pf-text-muted`                                            | Supporting text, comments, inactive states |
| `--pf-background`                                            | Page or article background                 |
| `--pf-surface`                                               | Tabs, cards, and subtle grouped surfaces   |
| `--pf-accent`                                                | Focus rings, active states, accent icons   |
| `--pf-accent-soft`                                           | Soft accent backgrounds                    |
| `--pf-accent-contrast`                                       | Text placed on solid accent backgrounds    |
| `--pf-{info\|success\|warning\|danger}`                      | Shared semantic colors                     |
| `--pf-{info\|success\|warning\|danger}-soft`                 | Shared semantic soft backgrounds           |
| `--pf-{info\|success\|warning\|danger}-ink`                  | Shared semantic icon and label text        |
| `--pf-{info\|success\|warning\|danger}-contrast`             | Text placed on solid semantic backgrounds  |
| `--pf-callout-{note\|tip\|warning\|danger}-{color\|ink\|bg}` | Type-specific callout overrides            |
| `--pf-border-subtle`                                         | Component borders                          |
| `--pf-border-muted`                                          | Active tabs and hover borders              |
| `--pf-font-sans`                                             | Prose and UI labels                        |
| `--pf-font-mono`                                             | File trees and code-adjacent labels        |
| `--pf-radius-sm`                                             | Small controls                             |
| `--pf-radius-md`                                             | Buttons, triggers, compact surfaces        |
| `--pf-radius-lg`                                             | Cards, callouts, tabs, file trees          |
| `--pf-radius-full`                                           | Pills and badges                           |

## Component Tokens

Use component tokens when a site needs layout-level tuning beyond the shared
palette.

| Token                                  | Used For                                                      |
| -------------------------------------- | ------------------------------------------------------------- |
| `--pf-badge-radius`                    | Badge corner radius                                           |
| `--pf-card-padding`                    | Card inner spacing                                            |
| `--pf-card-layout-gap`                 | Space between card icon and body                              |
| `--pf-card-body-gap`                   | Space between card title and content                          |
| `--pf-card-icon-size`                  | Card icon container size                                      |
| `--pf-card-icon-glyph-size`            | Icon size inside card icon containers                         |
| `--pf-card-title-size`                 | Card title font size                                          |
| `--pf-card-title-line-height`          | Card title line height                                        |
| `--pf-card-content-size`               | Card body font size                                           |
| `--pf-card-content-line-height`        | Card body line height                                         |
| `--pf-card-content-gap`                | Space between multiple body children                          |
| `--pf-card-grid-gap`                   | Space between cards in a `CardGrid`                           |
| `--pf-card-grid-margin`                | Vertical margin around a `CardGrid`                           |
| `--pf-file-tree-border`                | File tree outer border                                        |
| `--pf-file-tree-line`                  | File tree connector lines                                     |
| `--pf-image-gallery-preview-width`     | Visible preview width for the next gallery image              |
| `--pf-image-gallery-ratio`             | Fallback gallery item aspect ratio before images are measured |
| `--pf-steps-bullet-size`               | Step marker size                                              |
| `--pf-steps-bullet-margin`             | Gap below a step marker before the connector line starts      |
| `--pf-steps-line`                      | Step connector line color                                     |
| `--pf-steps-marker-background`         | Step marker background                                        |
| `--pf-steps-marker-foreground`         | Step marker text color                                        |
| `--pf-steps-start`                     | Counter starting offset for step numbering                    |

### VideoPlayer

VideoPlayer uses shared theme tokens for borders, radius, captions, and focus
rings. White overlay buttons stay readable over media in both themes. See
[VideoPlayer](/components/video-player/#styling) for its override tokens.

### AudioPlayer

AudioPlayer exposes semantic tokens for its main visual parts. Their defaults
delegate to the shared theme tokens wherever an equivalent token exists.

| Token                                          | Default                | Used For                    |
| ---------------------------------------------- | ---------------------- | --------------------------- |
| `--pf-audio-player-background`                 | `--pf-surface`         | Player background           |
| `--pf-audio-player-border-color`               | `--pf-border-subtle`   | Player border               |
| `--pf-audio-player-color`                      | `--pf-text`            | Player and control text     |
| `--pf-audio-player-title-color`                | `--pf-text-strong`     | Title text                  |
| `--pf-audio-player-meta-color`                 | `--pf-text-muted`      | Byline and playback time    |
| `--pf-audio-player-accent`                     | `--pf-accent`          | Active thumb, pause, focus  |
| `--pf-audio-player-font-family`                | `--pf-font-sans`       | Player font                 |
| `--pf-audio-player-margin`                     | `1.5rem`               | Player block margin         |
| `--pf-audio-player-radius`                     | `--pf-radius-lg`       | Player corner radius        |
| `--pf-audio-player-padding`                    | `0.75rem`              | Player inner spacing        |
| `--pf-audio-player-gap`                        | `0.875rem`             | Artwork-to-body gap         |
| `--pf-audio-player-artwork-size`               | `7.5rem`               | Artwork width and height    |
| `--pf-audio-player-artwork-radius`             | Player radius − padding ÷ 1.8 | Artwork corner radius       |
| `--pf-audio-player-title-size`                 | `0.9375rem`            | Title font size             |
| `--pf-audio-player-byline-size`                | `0.8125rem`            | Byline font size            |
| `--pf-audio-player-progress-color`             | `--pf-border-muted`    | Played progress             |
| `--pf-audio-player-progress-background`        | `--pf-border-subtle`   | Remaining progress          |
| `--pf-audio-player-progress-height`            | `0.375rem`             | Progress track height       |
| `--pf-audio-player-thumb-color`                | `--pf-text-muted`      | Slider thumb                |
| `--pf-audio-player-thumb-size`                 | `0.75rem`              | Slider thumb size           |
| `--pf-audio-player-control-color`              | `--pf-text`            | Control icons and speed     |
| `--pf-audio-player-control-size`               | `2rem`                 | Control button dimensions   |
| `--pf-audio-player-control-hover-background`   | `--pf-accent-soft`     | Control hover background    |
| `--pf-audio-player-speed-background`           | `--pf-border-subtle`   | Playback-speed background   |

<Callout type="tip" title="Scope tokens intentionally">
  Place overrides on `:root` for a site-wide theme, or on a docs layout wrapper
  when the components should differ from the rest of the application.
</Callout>

<Badge color="accent">Themeable</Badge>

## Prosefly Theme Projects

[Dahlia](https://astro-theme-dahlia.prosefly.dev/) and
[Lotus](https://astro-theme-lotus.prosefly.dev/) map their design systems to the
shared `--pf-*` component tokens. In either theme, start with
`src/theme.config.json` for accent, gray, radius, and color mode choices. Use
custom CSS only when you need lower-level control than the theme configuration
provides.