Contributing themes

A theme is one JSON file. Because it's data (colors, numbers and a closed set of words), anyone can write one without being able to run code on anyone's page.

Write a theme

Start from the built-in closest to what you want (Built-in themes), give it your own id, name and author, and change the values.

{
  "schema": 1,
  "id": "midnight-arcade",
  "name": "Midnight Arcade",
  "author": "mika",
  "description": "Neon on deep indigo. Pixel name, chips everywhere.",
  "mode": "dark",
  "colors": {
    "background": "#0D0B1E",
    "background2": "#151233",
    "surface": "#1B1740",
    "line": "#2E2966",
    "text": "#F4F1FF",
    "muted": "#A9A3D6",
    "accent": "#FF7AC6",
    "onAccent": "#1A0714",
    "highlight": "#7CF3FF"
  },
  "background": { "type": "gradient", "colors": ["#151233", "#0D0B1E"], "angle": 200 },
  "effects": { "scanlines": false, "grain": 0.06, "glow": true },
  "type": { "display": "pixel", "body": "sans", "label": "mono", "headingStyle": "prompt" },
  "shape": { "radius": 8, "avatar": "square", "border": 2 },
  "layout": {
    "order": ["projects", "building", "links", "tools", "pay_it_forward", "badges", "topics", "here_for"],
    "links": "chips",
    "projects": "list",
    "tools": "chips"
  }
}

Checklist

1. Validate against theme-1.json (Validate). Every field except description, background.angle and background.image is required, and no extra keys are allowed.
2. Check contrast (Contrast rules): text and muted at 4.5:1 or better on surface and background, and onAccent at 4.5:1 on accent. The schema can't check this; the API's theme validator does, and it will gate submissions.
3. Keep the accent flat. accent is one color; selected and pressed states never turn into gradients. Put gradients in background.
4. Try both lengths of page. A builder with two links and no projects, and one with twelve links, a long headline and every section.
5. Pick an id that's yours. Lowercase, digits and inner hyphens, 1–40 characters. Built-in ids (terminal, studio, pearl) are taken.

Roadmap

1. Built-ins (now)

   terminal, studio and pearl, a theme picker in the app, and pages that render the chosen theme on both the app and taste.dev.

2. Community library

   A public taste-themes GitHub repository. Open a pull request with your theme's JSON; CI validates it against the schema and checks contrast. Merged themes sync into the app's picker, and pages that wear them say "Theme by @you", linking to your page.

3. In-app theme editor

   Build a theme in the app with a live preview, upload a background image or sanitized SVG icons, and Remix any theme you like as a starting point.

Until the library opens, share what you make: post it on Taste with a screenshot.