Theme System Guide

This page is the live source of truth for consistent styling across components and site-wide design decisions. Match new UI work to the patterns below.

Back to Mechanics Back to Rules Open Technical Site Rules

Core Tokens

Theme tokens are defined in app/globals.css and applied through DaisyUI utility classes.

Token	Current Value	Primary Usage
`--app-shell-bg`	`#1e40af`	Primary app shell background behind non-home pages.
`--app-surface-1`	`#f3e8ff`	Root parent surface for `bg-base-100` wrappers (no border, no shadow).
`--app-surface-2`	`#dbeafe`	Secondary surface for nested content (`bg-base-50`).
`--app-surface-3`	`#dcfce7`	Tertiary surface for utility sections (`bg-base-200`).
`--app-surface-4`	`#fef9c3`	Quaternary surface for highlight blocks (`bg-base-300` + `border-base-300`).
`--app-surface-5`	`#ffedd5`	Accent surface for warm UI highlights (`bg-base-400` + `border-base-300`).
`--app-surface-6`	`#fee2e2`	Alert-leaning surface for stronger emphasis (`bg-base-500` + `border-base-300`).
`--app-border`	`#000000`	Default border color for UI chrome on themed pages.
`--app-radius`	`0.5rem`	Shared corner rounding via DaisyUI `rounded-box`.

Typography

Heading One Example

Heading Two Example

Heading Three Example

Base body text should be clear and direct for gameplay instructions and UI labels.

Use this for normal descriptive copy and section context.

Use muted text for hints, metadata, and less-critical details.

Label Style

Labels and helper text should use restrained contrast and consistent sizing.

Recommended class recipes

Section intro: mt-3 text-base-content/80
Helper copy: text-sm text-base-content/70
Labels: text-xs uppercase tracking-wide text-base-content/65

Color + Surfaces

Surface 1 (Root)

bg-base-100

Surface 2 (Child)

bg-base-50 border-base-300

Surface 3 (Child)

bg-base-200 border-base-300

Surface 4 (Child)

bg-base-300 border-base-300

Surface 5 (Child)

bg-base-400 border-base-300

Surface 6 (Child)

bg-base-500 border-base-300

Surfaces are intended to be layered parent-to-child. Keep Surface 1 borderless and nest deeper surfaces inside it.

Buttons

Use btn-primary for the main action, btn-secondary for blue support actions, btn-error for destructive actions, and btn-error btn-outline when you need lower-emphasis destructive actions.

Form Controls

Character Name

Use memorable names players can say out loud.

Class

Notes

Validation Messaging

Use semantic text classes for state messages.

Saved successfully.

Please fill out required fields before continuing.

Cards, Panels, and Tables

Character Summary Card

Reusable card shell for list views and quick actions.

Nested Panel

Keep nested blocks inside base-200 for separation.

Status	Example
Normal	Standard data row styling for mechanics and library tables.
Alternate	Zebra rows improve readability for dense game data.

Loading records...

Empty

No items found for this filter.

Error

Could not load data.

Spacing + Layout Rhythm

Prefer the app's established section rhythm: outer page spacing + card spacing + panel spacing.

Small Panel

p-3

Default Panel

p-4

Mid Section

p-5

Page Section

bg-base-100 p-6

Do / Don't

Compose sections with rounded-box bg-base-100 p-6.
Use bg-base-200 for nested panels inside cards.
Use semantic states like `text-success` and `text-error` for feedback.
Match copy hierarchy with `text-base-content`, then `.../80`, then `.../70`.

Don't

Invent one-off card shells with custom borders and ad-hoc spacing.
Introduce hardcoded screen colors unless there is a documented exception.
Mix many unrelated button styles in a single action group.
Skip empty/loading/error states in data-heavy components.

Print Theme Notes

Print layouts intentionally use a high-contrast document style. Keep print cards and sheets explicit with `print-page`, `bg-white`, `text-black`, and `border-black`.

When to use print styles

Dedicated print routes and printable card components.
Any layout expected to be exported or physically printed.
Grayscale helper copy with `text-gray-*` in print-specific markup.

Print Sample

Use explicit black borders and white background for reliable printer output.

Example shell: rounded-none border border-black bg-white p-4 text-black

Approved Pattern Recipes

Pattern	Class Recipe	Use Case
Page Section	`rounded-box bg-base-100 p-6`	Use for top-level parent surfaces with no border or shadow.
Nested Panel	`rounded-box border border-base-300 bg-base-200 p-3`	Use inside section cards for grouped controls or data.
Table Container	`overflow-x-auto rounded-box border border-base-300`	Wrap `table` elements to preserve layout and borders.
Muted Copy	`text-sm text-base-content/75`	Body helper text and secondary metadata.

Full governance and checklist details are documented in docs/theme-system.md.