Principles

tl;dr Principles give AI a vocabulary for a model's form and function. Whether they're precise scales or loose philosophy, these are what fuel your AI's decision making.

What are principles?

Principles are the foundational decisions that define your model. Instead of specifying exact values for every situation, you name your intentions: "primary" for your brand color, "muted" for subtle backgrounds, "radius" for how rounded things should be, "depth" for how UI should be layered, "motion" for how animation plays out, "genre" for design eras to draw inspiration from.

This abstraction is what makes taste models generalizable. AI can copy values, but it can also infer what each principle means and then map that framework to new situations. A "destructive" color isn't just red; it's your model's way of signaling danger or irreversible actions, and AI can use that context whether it's styling a delete button, writing an error message, or suggesting an illustration. This is a simple example, but the idea holds for more complex concepts like "reward" and "comfort" too.

Principle categories

For familiarity's sake, we bundle principles into categories you'll probably recognize:

Colors

The backbone of any visual identity. Color principles include:

• Surface colors - Background, foreground, card, and popover colors
• Brand colors - Primary, secondary, and accent colors (with matching foreground colors for text contrast)
• Semantic colors - Muted tones for subtle elements, destructive colors for errors and warnings
• Utility colors - Border, input, and focus ring colors

Each color principle comes with a matching "foreground" variant that ensures readable text contrast.

Typography

Font choices and text sizing:

• Font families - Your primary typeface and any secondary options
• Font sizes - Base size and any custom scale
• Line heights - Spacing between lines for readability
• Font weights - Reinforcing hierarchy and emphasis through thick- and thinness

Border radius

The roundness of your aesthetic. Most taste models define a base radius value, with optional small and large variants for different contexts, but we don't enforce shape here.

Shadows (Optional)

Elevation and depth effects. Shadow principles range from subtle (for cards and inputs) to dramatic (for modals and dropdowns). If your design is flat, skip shadows entirely.

Transitions (Optional)

Animation timing for interactive elements. Define consistent motion across hover states, focus indicators, and page transitions.

Required principles

For a taste model to work with Popmelt's preview system, it needs a handful of core principles. Your AI knows this and will define these using its best judgement even if you don't tell it how.

Surfaces: background, foreground, card, card-foreground, popover, popover-foreground

Brand: primary, primary-foreground, secondary, secondary-foreground, accent, accent-foreground

Semantic: muted, muted-foreground, destructive, destructive-foreground

Utility: border, input, ring, radius

Everything else (shadows, transitions, custom principles) is optional and adds richness to your model. AI may or may not add these based on your conversation, inspiration you offer, and a sample target you provide.

Principle references

Principles can point to other principles. For example, "card-foreground" might reference a fundamental "foreground" principle so they always stay in sync. This keeps your taste model lean and ensures related values don't drift apart. We nudge your AI to use references this way, and it generally will.

If you see an odd visual style pop up while working, ask your AI if it's sticking to the principles and it'll back on track.

Beyond code

While principles translate naturally to code (CSS variables, Tailwind themes, etc.), their value extends much further. The same principles that help style your buttons can also guide...

• Image generation - "Use only colors from the primary and accent principles"
• Copy tone - A model with bold, high-contrast principles might suggest punchier headlines
• Layout decisions - Generous spacing principles suggest airy layouts

Principles give AI a consistent lens for any design decision, not just the ones you've explicitly covered. That makes them powerful!

It can also tee up unexpected decisions by your AI. If you see something you're surprised by, ask where it came from: you can use what your AI tells you to fine-tune your model and the way you use it.

Common questions

Can I add custom principles?

Yes. Add any principle you need (custom colors, spacing scales, animation curves) and reference them throughout your model. Custom principles work alongside the required set.

Why "Principles" instead of "Design Tokens"?

We chose "principles" because it better reflects their broader function, more than just variables for color values.

It's also shorter, which makes it easier to type when you're chatting with AI. You can still use "design tokens" or "tokens" while working with our models, AI can usually figure out what you mean.

Do principles work with my existing framework?

Yes. AI translates principles into whatever format your project needs (CSS variables, Tailwind config, Swift colors, Figma styles). The principles themselves are intentionally framework-agnostic, so you can take them wherever you need to.

What's next

• Components - Creating structure out of principles
• Creating Taste Models - Define your own principles