The One Rule

Every visible UI element must come from an Eddie component or recipe. Consumer projects contain zero custom component styles. No exceptions.

This means:

• No custom CSS classes (.my-card, .sidebar-item, .form-row)
• No raw font-family, font-size, font-weight, or line-height
• No hardcoded colors, spacing pixels, or border values
• No Google Fonts <link> tags
• No Tailwind, Bootstrap, or any other CSS framework
• No inline styles unless using --ed-* CSS custom properties

If Eddie doesn't have a component you need, create a recipe — never write ad-hoc CSS in the consumer project.

What is Eddie?

Eddie is a themeable, framework-agnostic web component library built with Lit and TypeScript. It's published as four npm packages:

• @brad-frost-web/eddie-web-components — 80+ Lit-based web components
• @brad-frost-web/eddie-design-tokens — Design tokens (CSS custom properties, SCSS, JSON)
• @brad-frost-web/eddie-icons — SVG icon sprite library
• @brad-frost-web/eddie-recipes — Product-specific compositions built on core components

All components use the <ed-*> tag prefix and work in any framework or plain HTML.

Project Setup

1. Install packages

2. HTML: Add theme class

Available themes: bfw, bfw-dark, bfw-v9, wowee-zowee, we-are-here, altitude, southleft

3. JS entry point: Import tokens, fonts, and components

4. App CSS: ONLY the project-level reset

The only CSS your app should contain:

That's it. Nothing else. Eddie handles everything.

5. Vite config for local development

If linking to the Eddie monorepo source (not published npm packages):

Component Lookup Table

When building UI, use this table to find the right Eddie component. Never build these patterns from scratch.

Page Structure

Navigation

Typography & Content

Content Display

Forms

Feedback & Overlays

Interactive Patterns

Utility

Common Recipes

Recipes are product-specific compositions in @brad-frost-web/eddie-recipes. Use the <ed-r-*> tag prefix.

Design Tokens

Never use raw values. Always use Eddie CSS custom properties.

Spacing

Use var(--ed-spacing-*) for all spacing: 2xs, xs, sm, md, lg, xl, 2xl, 3xl, 4xl, 5xl.

Colors

Use semantic color tokens, never raw hex/rgb values:

Typography

Eddie components handle their own typography. Use <ed-heading> for headings, <ed-text-passage> for body text. Never set font-family, font-size, or line-height directly.

Borders

Composition Patterns

Basic Page

Sidebar Layout

Card Grid

Form

Creating Recipes (When Eddie Doesn't Have What You Need)

If a UI pattern doesn't exist in Eddie core, create a recipe component — never write custom CSS in the consumer project.

How to create a recipe

1. Scaffold: npm run eddie-recipes:plop (from repo root)
2. Choose a project directory (e.g., common/ for shared recipes, or a project-specific folder)
3. The recipe goes in packages/eddie-recipes/recipes/<project>/<recipe-name>/

Recipe conventions

• Tag prefix: ed-r- (e.g., <ed-r-pricing-card>)
• CSS class prefix: ed-r-c- (e.g., .ed-r-c-pricing-card)
• Extends EdElement (same base class as core components)
• Uses BEM naming, flat SCSS, and Eddie design tokens
• Should compose Eddie core components internally

Recipe file structure

Component API Conventions

When working with Eddie components, follow these naming patterns:

• variant — Primary stylistic variation (e.g., "primary", "secondary", "danger")
• size — Abbreviated t-shirt sizes: xs, sm, md, lg, xl
• text — General string content
• title — Heading content
• label — Form field labels
• iconName / iconPosition — Icon integration
• imgSrc / imgAlt — Image properties
• tagName — Override the HTML element rendered (e.g., tagName="h3")
• inverted — Boolean for dark-background color inversion
• href — Makes component render as a link

What NOT to Do

These are the most common mistakes. If an AI agent does any of these, it's wrong:

1. Writing custom CSS classes — If you're creating .my-sidebar, .step-indicator, .form-row, stop. Use an Eddie component or create a recipe.
2. Using Tailwind, Bootstrap, or any CSS framework — Eddie IS the framework. Don't layer anything on top.
3. Hardcoding fonts — Never add Google Fonts <link> tags. Import fonts.scss from the token package.
4. Raw pixel values — Use var(--ed-spacing-*) for spacing, var(--ed-border-radius-*) for radii.
5. Setting typography in app CSS — Use <ed-heading>, <ed-text-passage>, and <ed-text-link>.
6. Using <div> and <span> with custom styles — There's almost always an Eddie component for it.
7. Building layout with CSS Grid/Flexbox directly — Use <ed-layout>, <ed-grid>, <ed-layout-container>.
8. Creating buttons with <button> + custom styles — Use <ed-button>.
9. Ignoring the import pattern — Every Eddie component must be imported in your JS entry point before use.

For Claude / AI Agents: Behavioral Rules

If you are an AI assistant building UI for a Brad Frost Web project:

1. ALWAYS use Eddie components. Do not write custom HTML elements with custom CSS. Every UI element has an Eddie equivalent — find it in the table above.
2. ALWAYS use design tokens. If you need to set a color, spacing, border, or typography value, use an --ed-* CSS custom property. Never hardcode values.
3. NEVER add CSS frameworks. No Tailwind, Bootstrap, Material UI, or any other UI library. Eddie replaces all of them.
4. NEVER write custom component CSS in consumer projects. If Eddie doesn't have what you need, create a recipe in the eddie-recipes package.
5. Import every component you use in the JS entry point. Eddie components are web components and must be registered before use.
6. Check the component table before building anything. If you're about to write a <div class="card">, stop — use <ed-card>.
7. Follow the entry point pattern. Every project needs: fonts import → tokens import → component imports → theme class on <html>.
8. When in doubt, compose. Eddie components are designed to nest and compose. A page is just Eddie components all the way down.

Reference Links

• Storybook (live component explorer): ds.bradfrost.com/storybook
• npm packages: @brad-frost-web on npm
• Source code: github.com/bradfrost/eddie-design-system