Customizing themes

Five layers, increasing in scope. Most projects stop at layer two.

1. Override colors

Five hex tokens cover most rebrands.

{
  "theme": "tang",
  "colors": {
    "primary": "#0ea5e9",
    "light":   "#38bdf8",
    "dark":    "#0284c7",
    "background": { "light": "#FFFFFF", "dark": "#0A0A0A" }
  }
}

See Schema → Colors for the full token table.

2. Override fonts

{
  "fonts": {
    "heading": { "family": "DM Sans", "weight": "400;500;700" },
    "body":    { "family": "Inter" }
  }
}

Tangly fetches matching weights from Google Fonts. Self-hosted: set source to a URL.

{
  "fonts": {
    "body": {
      "family": "Custom Sans",
      "source": "/fonts/custom-sans.woff2",
      "format": "woff2"
    }
  }
}

See Schema → Fonts & styling.

3. Override CSS variables

For sidebar widths, content column, line heights, radii — drop a theme/styles/theme.css at your project root. The file is concatenated after the bundled theme so your declarations win.

/* theme/styles/theme.css */
:root {
  --tangly-sidebar-width: 20rem;
  --tangly-content-max-width: 52rem;
  --tangly-radius: 0.75rem;
}

.dark {
  --tangly-color-bg: #050505;
}

Every theme exposes the same token namespace (--tangly-color-*, --tangly-font-*, --tangly-sidebar-*, etc.). See each theme’s reference page for its specific defaults.

4. Shadow components

For component-level changes — restyling a Card, replacing the topbar layout, adding a custom callout variant — drop a matching .astro file under theme/.

The shadowed component receives the same props as the built-in. See Custom components for the full pattern.

5. Eject

For full control — custom Vite plugins, custom Astro integrations, removing parts of the runtime — run:

tangly eject

This materializes the synthesized Astro project to .tangly/. Edit anything. Tangly’s CLI keeps working but now operates on the ejected project.

One-way operation. Commit before running.

See tangly eject for what gets written and how to roll back if you regret it.

What lives where

Cross-theme patterns

Token names are the same across all five built-in themes. Custom CSS overrides written for tang work on geist, pith, etc. — only the values differ.

/* This works under any theme. */
:root {
  --tangly-content-max-width: 50rem;
}

This is by design: @tanglydocs/theme-ui is the single component shell every theme renders through.