UI Customization
TimeTiles provides a layered customization system — from simple color changes to full CSS overrides — with both built-in themes and admin dashboard controls.
Built-in Themes
The @timetiles/ui package ships two built-in themes that users can switch between at runtime:
| Theme | Description |
|---|---|
| Cartographic | Earth-tone palette inspired by vintage maps (default) |
| Modern | Clean, contemporary design with vibrant accents |
Users switch themes using the Palette icon in the site header. The selection persists in the browser via localStorage. Both themes include full light and dark mode support.
Built-in themes support custom themes via CSS variables. See the UI package documentation for details on creating additional themes.
Customization Layers
| Layer | What it controls | Where to configure |
|---|---|---|
| Built-in Themes | Two bundled color/style packages | Palette icon in header (user-facing) |
| Theme Presets | Custom CMS-managed theme packages | /dashboard/collections/themes |
| Site Branding | Per-site color and style overrides | /dashboard/collections/sites |
| Block Styles | Per-block spacing, visibility, separators | Page builder (per block) |
| Custom CSS | Arbitrary CSS scoped to your site | /dashboard/collections/sites |
| Layout Templates | Page structure (header, footer, width) | /dashboard/collections/layout-templates |
Each layer overrides the one above it. CMS theme presets override the built-in themes. A site’s inline colors override its theme preset. Custom CSS overrides everything.
Theme Presets (CMS)
Theme presets are reusable visual configurations shared across sites. Create one at /dashboard/collections/themes. These override the built-in themes when assigned to a site.
Colors — 11 semantic tokens controlling the entire UI:
| Token | Controls | Example |
|---|---|---|
primary | Navigation, headings, buttons | #1a365d |
primaryForeground | Text on primary backgrounds | #ffffff |
secondary | Secondary accent elements | #c05621 |
background | Page background | #f5f0e8 |
foreground | Default text color | #2d2d2d |
card | Card backgrounds | #ede8db |
muted | Subtle backgrounds | #e8e3d6 |
accent | Success states, highlights | #2f6b3a |
destructive | Error/danger states | #c53030 |
border | Border color | #d4cfc2 |
ring | Focus ring color | #3182ce |
Dark mode colors are optional — leave empty to use automatic dark mode derivation.
Typography:
| Pairing | Headings | Body |
|---|---|---|
| Editorial | Playfair Display (serif) | DM Sans (sans-serif) |
| Modern | Inter (sans-serif) | Geist Sans (sans-serif) |
| Monospace | Space Mono | IBM Plex Mono |
Visual style — border radius (sharp, rounded, pill) and density (compact, default, comfortable).
Themes use Payload’s built-in versioning — every change is tracked and reversible.
Site Branding
Each site can override its theme preset with inline settings. Edit the Branding section at /dashboard/collections/sites.
- Title — overrides platform site name in browser tabs and headers
- Logo — separate uploads for light and dark themes
- Favicon — custom favicon for this site
- Color overrides — same 11 tokens as theme presets, highest priority
- Typography & style — font pairing, border radius, density
Colors can be any valid CSS value: hex (#3b82f6), OKLCH (oklch(0.58 0.11 220)), RGB, or HSL.
Block-Level Styles
Every block in the page builder has a Block Style section:
| Control | Options |
|---|---|
| Padding top/bottom | None, Small, Medium, Large, Extra Large |
| Max width | 768px, 1024px, 1152px, 1280px, Full |
| Background color | Any CSS color |
| Anchor ID | Creates a #id scroll target |
| Hide on mobile/desktop | Toggle visibility by screen size |
| Separator | None, Line, Gradient Fade, Wave |
Use cases: Show different hero blocks on mobile vs. desktop. Add #pricing anchor IDs for navigation links. Alternate padding and separators for visual rhythm.
Custom CSS
For cases where structured controls aren’t enough. Edit the Custom Code section on any site.
| Field | Purpose |
|---|---|
| Custom CSS | CSS rules scoped to this site |
| Head HTML | Analytics, meta tags, custom fonts |
| Body Start HTML | Tag managers, noscript fallbacks |
| Body End HTML | Tracking scripts |
CSS is automatically scoped via [data-site="your-site-slug"]. Target blocks with [data-block-type="hero"] or [data-block-id="abc123"].
Security — these patterns are stripped automatically: @import, url(), javascript:, expression(), position: fixed.
Layout Templates
Layout templates control the structural frame of pages. Create at /dashboard/collections/layout-templates:
| Setting | Options | Default |
|---|---|---|
| Header variant | Marketing, App, Minimal, None | Marketing |
| Sticky header | Yes / No | Yes |
| Footer variant | Full, Compact, None | Full |
| Content max width | 768px, 1024px, 1152px, 1280px, Full | 1152px |
Assignment: Set a site-wide default on the site, then override per page. Resolution order: page override > site default > platform default.
| Template example | Header | Footer | Width | Use case |
|---|---|---|---|---|
| Landing Page | Marketing | Full | Full | Homepage, marketing |
| Documentation | Minimal | Compact | Medium | Help pages, guides |
| App View | App | None | Full | Explore/map interface |
| Clean | None | None | Full | Embeds, iframes |
Priority Order
When multiple layers are configured, they resolve highest priority first:
- Custom CSS — overrides anything
- Inline site branding — overrides theme preset
- CMS theme preset — overrides built-in themes
- Built-in themes — Cartographic (default) or Modern, selected by the user
- Platform defaults — base design system