Brand Tokens

The brand token layer is the public theming API of this template system. These are the tokens child templates replace to apply customer branding. All other tokens (spacing, neutral colors, component dimensions) are structural and managed by the parent template.

  1. Brand Colors
  2. Font Families
  3. How to Override

Brand Colors

Three semantic color roles map to customer brand hues. The actual palette options (blue, yellow, cyan, etc.) are defined in core/color.tokens. Replace the references in contextual/brand.tokens to change which palette maps to each role.

  1. Primary
  2. Secondary
  3. Accent

Primary

  • Primary-100

    var(--color-primary-100)
     light: #c0cefc dark: #fff6d6

  • Primary-200

    var(--color-primary-200)
     light: #739ddd dark: #ffeeb3

  • Primary-300

    var(--color-primary-300)
     light: #083273 dark: #ffe58a

  • Primary-400

    var(--color-primary-400)
     light: #062656 dark: #ffdc61

  • Primary-500

    var(--color-primary-500)
     light: #052049 dark: #ffd43b

  • Primary-600

    var(--color-primary-600)
     light: #041a3e dark: #ffcd1a

  • Primary-700

    var(--color-primary-700)
     light: #031637 dark: #fac300

  • Primary-800

    var(--color-primary-800)
     light: #02102b dark: #dbab00

  • Primary-900

    var(--color-primary-900)
     light: #010a20 dark: #b88f00

Secondary

  • Secondary-100

    var(--color-secondary-100)
     light: #fff6d6 dark: #c0cefc

  • Secondary-200

    var(--color-secondary-200)
     light: #ffeeb3 dark: #739ddd

  • Secondary-300

    var(--color-secondary-300)
     light: #ffe58a dark: #083273

  • Secondary-400

    var(--color-secondary-400)
     light: #ffdc61 dark: #062656

  • Secondary-500

    var(--color-secondary-500)
     light: #ffd43b dark: #052049

  • Secondary-600

    var(--color-secondary-600)
     light: #ffcd1a dark: #041a3e

  • Secondary-700

    var(--color-secondary-700)
     light: #fac300 dark: #031637

  • Secondary-800

    var(--color-secondary-800)
     light: #dbab00 dark: #02102b

  • Secondary-900

    var(--color-secondary-900)
     light: #b88f00 dark: #010a20

Accent

  • Accent-100

    var(--color-accent-100)
     light: #e6fcff dark: #fff6d6

  • Accent-200

    var(--color-accent-200)
     light: #b6f4ff dark: #ffeeb3

  • Accent-300

    var(--color-accent-300)
     light: #74eaff dark: #ffe58a

  • Accent-400

    var(--color-accent-400)
     light: #0dd3f5 dark: #ffdc61

  • Accent-500

    var(--color-accent-500)
     light: #0cc0df dark: #ffd43b

  • Accent-600

    var(--color-accent-600)
     light: #0bafcb dark: #ffcd1a

  • Accent-700

    var(--color-accent-700)
     light: #088095 dark: #fac300

  • Accent-800

    var(--color-accent-800)
     light: #077183 dark: #dbab00

Font Families

Three semantic font family aliases are defined in contextual/brand.tokens. They reference the actual font stacks in core/typography.tokens. To change fonts, either update the alias references (e.g. point heading to a different core family) or update the core font stacks directly.

  • Base Family

    Resolves to: var(--font-family-sans)

    The quick brown fox jumps over the lazy dog 0123456789 

    var(--font-family-base)

  • Heading Family

    Resolves to: var(--font-family-expressive)

    The quick brown fox jumps over the lazy dog 0123456789 

    var(--font-family-heading)

  • Mono Family

    Resolves to: var(--font-family-code)

    The quick brown fox jumps over the lazy dog 0123456789 

    var(--font-family-mono)

How to Override Brand Tokens

Two approaches are available, depending on how much customization is needed.

Option A — CSS custom property override (simplest)

Provide a user.css file in the child template's media directory. No build tooling required. Best for color adjustments when the font stacks stay the same. 

/* media/templates/site/jcrafts_customer/css/user.css */
:root {
  /* Override primary brand color scale */
  --color-primary-100: #e8f4fd;
  --color-primary-500: #2e86c1;
  --color-primary-800: #1a5276;

  /* Override secondary */
  --color-secondary-500: #f39c12;

  /* Override font families */
  --font-family-base: "Open Sans", Arial, sans-serif;
  --font-family-heading: "Montserrat", Verdana, sans-serif;
}

Option B — Token file override (full build)

Replace contextual/brand.tokens in the child template build. This produces the most consistent output because all derived tokens (surface colors, component tokens) automatically update when the brand palette changes.

  1. Copy node_modules/@simplysmart-it/tmpl-jcrafts/design-system/src/assets/tokens/contextual/brand.tokens to tokens/brand.tokens in the child repo.
  2. Update the color references (e.g. replace { base.color.blue.*} with { base.color.teal.*} for primary) and the font family values.
  3. Run npm run build — Terrazzo compiles the tokens and Sass generates user.css. 
{
  "base": {
    "color": {
      "primary": {
        "500": { "$value": "{base.color.teal.500}", "$type": "color" }
      }
    },
    "font": {
      "family": {
        "heading": { "$value": "{base.font.family.expressive}", "$type": "fontFamily" }
      }
    }
  }
}

Stable API guarantee

The following CSS custom properties are the stable public API — child templates using only these properties will not break when the parent template updates:

  • --color-primary- { 100–900}
  • --color-secondary- { 100–900}
  • --color-accent- { 100–800}
  • --font-family-base, --font-family-heading, --font-family-mono

Neutral colors, spacing, surface colors, and component tokens are structural — they automatically reflect brand changes but should not be overridden directly.