color_theory_basics v1.0.0

name: "color_theory_basics" description: "Choose colors for websites, slides, brand materials, or app UI: build a palette from a base color using harmony rules, assign usage roles, and verify WCAG contrast ratios. Triggers on: pick a color palette, brand colors, what colors go together, accessible color combinations, text contrast check, analogous vs complementary colors." metadata: { "includeInPrompt": true }

Color Theory Basics

Purpose

Pick colors that work together for any visual deliverable: site, deck, brand kit, app UI. Covers the color wheel, harmony rules, palette building, and contrast checks. It does not cover video color grading (LUTs, vectorscopes, shot matching); the catalog's separate color-grading skill owns that.

Workflow

1. Start from one base color the client likes or the brand already has. If none exists, ask for a mood word (calm, bold, premium, playful) and propose one hex.
2. Pick a harmony rule for the palette:

• Monochromatic: base color plus tints (mix toward white) and shades (mix toward black). Safest default; use when in doubt.
• Analogous: base plus the two hues next to it on the wheel (within ~30-60 degrees). Calm and cohesive; good for backgrounds and secondary UI.
• Complementary: base plus the hue opposite on the wheel (~180 degrees). High energy; reserve the complement for accents and calls to action, not large areas.
• Triadic: base plus two hues evenly spaced (~120 degrees apart). Lively but balanced; keep one dominant and the other two as accents.

1. Build the palette: 1 dominant color (60% of the surface), 1-2 secondary colors (30%), 1 accent (10%). Stop adding colors when every role is filled; most designs need 3-4 colors total, 5 at most.
2. Assign roles explicitly: background, primary text, secondary text, primary button/link, accent/highlight, success/error (stick with green/red conventions here unless told otherwise).
3. Check contrast with the script below for every text/background pair and every meaningful icon or form-field border. Targets: 4.5:1 for normal text, 3:1 for large text (18pt+ or 14pt+ bold). Treat those as floors, not aspirations; aim a bit above them.
4. Sanity pass: view the palette at small sizes and on the actual device if possible. Convert it to grayscale; if two elements that must be distinguishable become identical, the hue difference is doing all the work and you need a lightness gap too. Never rely on color alone to convey meaning (errors, statuses); pair it with text or an icon.

Contrast ratio calculator (self-contained)

Save as contrast_check.py and run with python3 contrast_check.py <fg-hex> <bg-hex>, e.g. python3 contrast_check.py "#1a1a1a" "#ffffff". Verified working on python3 with standard library only.

python
import sys

def lin(c):
    c = c / 255.0
    return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4

def luminance(hex):
    hex = hex.strip().lstrip('#')
    r, g, b = int(hex[0:2], 16), int(hex[2:4], 16), int(hex[4:6], 16)
    return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b)

def ratio(h1, h2):
    l1, l2 = luminance(h1), luminance(h2)
    hi, lo = max(l1, l2), min(l1, l2)
    return (hi + 0.05) / (lo + 0.05)

if __name__ == '__main__':
    fg, bg = sys.argv[1], sys.argv[2]
    r = ratio(fg, bg)
    def verdict(t):
        return 'PASS' if r >= t else 'FAIL'
    print(f"{fg} on {bg}: {r:.2f}:1")
    print(f"  normal text (>=4.5): {verdict(4.5)}")
    print(f"  large text (>=3.0):  {verdict(3.0)}")

Output Contract

Deliver: the palette as named colors with hex values, each color's role (background, text, button, accent, status), and a contrast table showing each text/background pair's ratio and PASS/FAIL against the 4.5:1 and 3:1 floors. Include the harmony rule you used and one sentence on why it fits the brief. If a pair fails, say which color to darken or lighten and by how much (a rough hex adjustment is fine).

Operating Rules

1. Defaults with exceptions: monochromatic is the default palette shape, complementary accents are the default for energy, the 60/30/10 split is the default distribution. Break any of these when the brief clearly calls for it; say why in one sentence.
2. Always assign roles before finalizing; a pretty palette with no role assignments is unfinished work.
3. Contrast floors are non-negotiable for text that must be read (4.5:1 normal, 3:1 large). Decorative elements that carry no information may sit below the floors; say so explicitly when you allow it.
4. Keep palettes small: 3-4 colors beats 7. Every extra color needs a job.
5. Do not quote WCAG levels (AA/AAA) or ratio numbers beyond the two floors without verifying them fresh; the floors above are the stable, long-standing values.