Session 1: Foundations & the Design-to-Code Mental Model

1. Foundations & the Design-to-Code Mental Model

Title

Session 1 · shadcn/ui + Figma

Designers hand off pixels; developers rebuild in a system. This series closes that gap - starting with how Tailwind, Radix and shadcn actually relate.

2. What you will be able to do

Objectives

You already know Figma. By the end of this session you can speak the three words developers use all day - Tailwind, Radix, shadcn - and know exactly which one does what. Concretely, you can:

• Explain how Tailwind, Radix, and shadcn/ui relate as three stacked layers.
• Say why shadcn components are copied into your repo and owned, not installed and locked.
• Navigate the Figma shadcn kit - Pages, Assets panel, Variables panel - with confidence.

• Map each Figma concept to its code twin: instance to component, bound variable to CSS variable, property to prop.
• Use a 'which layer owns this?' recipe to place any decision.
• Recreate a small Aster profile card from kit parts: Card + Avatar + Badge + Button.

3. The design-to-code gap

Concept

The classic handoff: a designer exports a pixel-perfect frame, a developer eyeballs it and rebuilds it from scratch in their own system. Spacing drifts, colors get re-picked, and the two artifacts slowly diverge.

The fix isn't a better export - it's a shared system on both sides. When your Figma kit and the code are built from the same components and the same tokens, handoff becomes translation, not reconstruction.

This session gives you the vocabulary for that shared system. Everything after builds your Aster studio landing page on top of it.

4. Where we're headed: Aster

Concept

The running project across all six sessions is Aster - a landing page for your own freelance design studio. Brand: a violet primary oklch(0.55 0.24 285), base radius 0.625rem, project folder aster-site.

The page has five sections we'll return to constantly: navbar, hero, feature grid, pricing, footer. Today stays entirely in Figma - no terminal yet - but every example pushes Aster one step forward.

The three layers

Tailwind, Radix, shadcn - what each one owns.

Copy-in, own it

Why shadcn lives in YOUR repo, not npm.

The Figma kit

Pages, Assets, Variables - mirrored 1:1 in code.

5. The Three Layers

Section

Part 1

6. Layer 1 - Tailwind

Concept

Tailwind is a utility-first CSS system. Instead of writing a stylesheet with named classes like .card { padding: 16px }, you compose the style directly in the markup out of tiny single-purpose classes.

Tailwind — A utility-first CSS system: you style an element by composing many small, single-purpose classes (p-4, flex, gap-2, bg-primary) right on the element, instead of writing separate CSS rules.

Each class maps to one declaration. p-4 sets padding: 1rem, flex sets display: flex, gap-2 sets gap: 0.5rem. Nothing is prebuilt - Tailwind gives you the paint, not the furniture.

7. Break it if you can: Layer 1 - Tailwind

Counterexample

8. Tailwind: a class string, decoded

Worked example

Here's a small chunk of the Aster hero's call-to-action row. Every class is one CSS declaration - read it left to right.

<div class="flex items-center gap-3 p-4">
  <!-- flex row, vertically centered, 12px gap, 16px padding -->
</div>

The spacing scale is fixed and predictable: base unit is 0.25rem = 4px, so gap-3 = 12px and p-4 = 16px. No magic numbers - the scale keeps every gap on the grid.

9. Fill in: CSS it produces for Tailwind: a class string, decoded

Comparison

10. Layer 2 - Radix

Concept

Radix (Radix Primitives) is a set of headless behavior primitives. It ships the hard, invisible parts of an interactive component - focus management, keyboard navigation, ARIA roles - and no styling at all.

Radix — Unstyled ('headless') accessible UI primitives. Radix provides behavior and accessibility - focus trapping, keyboard nav, correct ARIA roles - but ships zero visual styling; you bring the skin.

Think of a dialog: Radix guarantees focus is trapped inside it, Esc closes it, focus returns to the trigger, and screen readers announce it correctly. What it looks like is entirely up to you.

11. By analogy: Layer 2 - Radix

Analogy

12. Radix: behavior with no skin

Worked example

A raw Radix primitive renders correct structure and behavior but is visually unstyled - it looks like nothing until you add classes.

// Radix gives the behavior + ARIA, no styling:
<Dialog.Root>
  <Dialog.Trigger>Open</Dialog.Trigger>
  <Dialog.Content>...</Dialog.Content>
</Dialog.Root>

Out of the box this traps focus, wires aria-* attributes, and handles Esc and Tab. But it has no padding, no background, no rounded corners. Radix is the skeleton.

Getting accessibility right by hand is genuinely hard. Radix is why shadcn components are accessible without you having to think about ARIA on day one.

13. Layer 3 - shadcn/ui

Concept

shadcn/ui is the assembled layer: styled components built by putting a Tailwind skin on Radix behavior. A shadcn Button is Radix-grade behavior plus a class string that gives it Aster's look.

shadcn/ui — A collection of styled UI components built on Radix primitives and Tailwind. You copy the component source into your own repo (components/ui/) and own it - it is not an installed, locked dependency.

Crucially, shadcn is not a package you install and hide behind. You copy each component's source into your project and it becomes your code - the single most important idea in this deck, and the whole of Part 2.

14. Take the definitions apart: Radix vs shadcn/ui

Definition probe

15. Three stacked layers

Intuition

Read the stack bottom-up. Radix is the skeleton: it moves correctly. Tailwind is the paint: it composes the look. shadcn/ui is the assembled, finished component that combines both - and it lives in your repo.

Each layer has one job. When something's wrong, this stack tells you where to look: broken keyboard focus is a Radix concern; a wrong color is a Tailwind/token concern; a component's whole shape is shadcn.

16. Something is wrong here: 'Radix gives you the pretty styling'

Anomaly

17. Trap: 'Radix gives you the pretty styling'

Trap

18. Something is wrong here: 'Tailwind is a component framework like Bootstrap'

Anomaly

19. Trap: 'Tailwind is a component framework like Bootstrap'

Trap

20. Break it on purpose: 'Tailwind is a component framework like…

Break the constraint

21. How the three fit together

Concept

One sentence to keep: shadcn = Radix (behavior) + Tailwind (styling), copied into your repo. Two dependencies do the heavy lifting; the visible component is yours.

22. What each one costs: How the three fit together

Trade off

23. Tailwind's spacing scale is a grid

Intuition

Tailwind's spacing isn't arbitrary. One base unit is 0.25rem = 4px, and every step is a multiple of it. So the number in the class is the multiplier: p-4 = 4 units = 16px.

This is why designs stay on a grid. If your Figma Auto-Layout gaps are 8 and 16, they land exactly on gap-2 and gap-4 - no odd 13px values to reverse-engineer at handoff.

24. Teach it back: Tailwind's spacing scale is a grid

Explain it

25. Anatomy of a shadcn Button

Concept

A shadcn component isn't a black box - it exposes a small, deliberate set of knobs. The Button, which Aster's navbar and hero both use, has two axes you'll set constantly.

Variants swap the whole look: default, secondary, destructive, outline, ghost, link. Sizes change the footprint: default, sm, lg, icon.

26. What rests on this: Anatomy of a shadcn Button

Socratic

27. Reading the Button in code and Figma

Worked example

In code, you set variant and size as props. In Figma, the exact same choices are the Button instance's variant properties - the twin relationship you'll rely on all series.

// Aster hero CTA
<Button variant="default" size="lg">Start a project</Button>

// Aster navbar link-style button
<Button variant="ghost" size="sm">Work</Button>

Setting variant="ghost" in Figma's properties panel picks the same style set that variant="ghost" picks in code. You are choosing among the component's built-in options, not restyling by hand.

28. The states that matter

Concept

A real component has more than one look. Design each meaningful interactive state, because the code will render all of them - and Radix drives when each applies.

• default - the resting look.
• hover - pointer over it.
• focus-visible - the ring, shown only for keyboard focus (focus-visible:ring-*), not mouse clicks.
• active - being pressed.
• disabled - non-interactive, dimmed.

The focus-visible ring is the one designers most often forget. It's an accessibility feature Radix and Tailwind wire up; design it so keyboard users can see where they are on the Aster page.

29. All three layers in one Button

Worked example

Here is a single Aster CTA with each layer's contribution labeled. Read it as: Radix behavior, Tailwind classes, all wrapped in a shadcn component you own.

// shadcn <Button> (your file) = Radix behavior + Tailwind skin
<Button
  className="gap-2 px-4 rounded-lg focus-visible:ring-2"
>
  Start a project
</Button>

Change the look? Edit the classes. Change the behavior? That's Radix underneath. Need a whole new variant? Edit the component file - it's yours. The three-layer map tells you where to go every time.

30. Copy-In, Own the Code

Section

Part 2 · The key idea

31. Two models of a component library

Concept

There are two ways a component library can reach your project, and the difference decides how much control you have.

Closed / installed (MUI, Ant Design): you npm install a package. The component source lives in node_modules/ - code you don't own and shouldn't edit. You style it only from the outside, through the props and theme options the authors exposed.

Copy-in / owned (shadcn/ui): the CLI copies the component's actual source into your repo, at components/ui/. It's now your file. You read it, edit any line, and it updates only when you choose to re-pull it.

32. node_modules vs your repo

Intuition

Left: a closed library is a locked box in node_modules/. You can pass it props, but you can't open it and change how it's built.

Right: a shadcn component is an open file in your own source tree. Same as any other file you wrote - fully readable, fully editable, versioned in your git history.

33. What rests on this: node_modules vs your repo

Socratic

34. Owning it: adding an Aster brand variant

Worked example

Say Aster needs a special 'brand' button that isn't one of the built-in variants. With shadcn, button.tsx is your file, so you just add a line to the variant map.

// components/ui/button.tsx - your own file
const buttonVariants = cva("...", {
  variants: { variant: {
    default: "bg-primary text-primary-foreground",
    brand: "bg-violet-600 text-white shadow-lg", // added
  } },
})

Now <Button variant="brand"> works everywhere. You didn't fork a package or fight the library - you edited a file you own.

With a closed library, a variant the authors didn't ship simply isn't available - you'd be stuck overriding styles from the outside.

35. Something is wrong here: 'shadcn is an npm library you install and can't edit'

Anomaly

36. Trap: 'shadcn is an npm library you install and can't edit'

Trap

37. Why copy-in wins for Aster

Concept

For a bespoke brand like Aster, ownership is the whole point: no lock-in, full control, and updates on your terms.

• Full control: any line is editable - variants, markup, behavior wiring.
• No lock-in: you're not tied to a package's release cycle or its opinions.
• Updates on your terms: re-pull a component when you want, and diff it against your version.
• Readable: reading the source is how you tweak it with confidence.

38. The closed-library override tax

Worked example

Here's what ownership saves you from. With a closed library you can't reach the internal element, so you stack ever-more-specific selectors and !important to force a change from outside.

/* fighting a closed library from outside */
.MuiButton-root .MuiButton-label {
  color: var(--primary) !important; /* please win */
}

It's brittle: a library update can rename that inner class and silently break your override. You never touched the real markup - you just shouted louder than it.

// shadcn: edit the one line in YOUR file instead
// components/ui/button.tsx
"text-primary" // done - no !important, no selector war

39. Updates on your terms

Concept

'You own it' cuts both ways: nothing auto-updates behind your back. When shadcn improves a component, you choose whether and when to pull the new version in.

Because both your version and the new one are just files, you diff them - see exactly what changed, keep your Aster edits, and take the upstream improvements you want. No surprise breakage on a routine npm update.

40. A 'Which Layer Owns This?' Recipe

Section

Part 3 · Pattern

41. Rebuild the recipe: Which layer owns this decision?

Ranking

42. Which layer owns this decision?

Pattern

When you hit any UI decision, route it to the layer that owns it. Ask these in order:

1. Is it about behavior - focus, keyboard, ARIA, open/close logic? That's Radix.
2. Is it about utility styling - spacing, color, radius, layout? That's Tailwind (usually via a token).
3. Is it the whole assembled component you place and can edit - its structure and variants? That's shadcn/ui (your file).

One nuance: colors and radius flow through design tokens (CSS variables). So 'change the primary color' is a token change that Tailwind classes then read - not a hand-edit on every component.

43. Where does it stop working: Which layer owns this decision?

Edge cases

44. Running the recipe on Aster

Worked example

Four real decisions from the Aster build. For each, ask the recipe's questions and route it to the owning layer before you read the answer.

Notice the first and last are both Tailwind, but the color one goes through a token so it stays consistent everywhere. The recipe scales to every choice you'll make this series.

45. Where does each piece belong: Session 1: Foundations & the Design-to-Code…

Sorting

46. Rule out three: Check: place the decision

Elimination

47. Check: place the decision

Check

Aster's pricing section has an accordion of FAQs. Pressing Esc should close an open item, and focus should stay managed correctly. Which layer owns that?

48. Answer it before you see the options: Check: closed vs copy-in

Prediction

49. Check: closed vs copy-in

Check

You need to change the internal markup of a Button - not just its props - so it renders an extra wrapper element. Compare a closed library (MUI) with shadcn.

50. Touring the Figma shadcn Kit

Section

Part 4

51. The kit mirrors the code 1:1

Concept

The Figma shadcn kit isn't decoration - it's the design-side twin of the codebase. Three panels do the work, and each maps to something concrete in code.

Pages

Organize the kit into sections (primitives, components, examples).

Assets panel

The component library - drag instances onto the canvas.

Variables panel

Design tokens = the CSS variables in globals.css.

52. Which is which: The kit mirrors the code 1:1

Matching

53. Pages - organizing the kit

Concept

Pages (top-left of the Figma file) split a large kit into navigable sections - for example a cover page, a components page, and an examples page. They're organization only; they don't change how anything renders.

Loosely, a page is like a folder in the project - a way to keep the button gallery separate from the assembled example screens. You'll live mostly on the components and examples pages.

54. Auto Layout is flexbox

Concept

One mapping unlocks most of Figma-to-Tailwind: Auto Layout is flexbox. The controls you already use in Figma have direct Tailwind twins - so the way you lay out Aster's navbar is the way it's coded.

55. The Aster navbar, both ways

Intuition

Aster's navbar is a horizontal Auto-Layout frame with space between the logo and the links. In code that's exactly flex flex-row items-center justify-between - the logo hugs left, the links and Hire button sit right.

You didn't guess the CSS. You read it off the Auto-Layout panel: direction, alignment, and the space-between setting each name their own class.

56. What rests on this: The Aster navbar, both ways

Socratic

57. Composition: components to blocks to pages

Concept

Small parts compose upward. A component (Button) sits inside a block (a whole navbar or pricing section - shadcn calls these 'blocks'), and blocks compose into a page (the full Aster landing page).

Figma mirrors this: instances nest inside a section frame, sections stack into a screen. Same shape on both sides - which is why the kit's example screens read like real page code.

58. The Assets panel - the component library

Concept

The Assets panel is the kit's component library. Every main component - Button, Card, Avatar, Badge - appears here. You drag one onto the canvas to place an instance of it.

Assets panel — The Figma panel that lists all published/available components in a file. Dragging one onto the canvas creates an instance - a live copy that stays linked to the main component.

An instance is the design-side twin of an imported component in code. Placing a Button instance in Figma is the same act as writing <Button /> in a file.

59. What rests on this: The Assets panel - the component library

Socratic

60. The Variables panel - design tokens

Concept

The Variables panel holds the kit's design tokens: named values like a primary color or a base radius. Bind a layer's fill to the primary variable and it now references that token instead of a raw hex.

design token — A named, reusable design value (a color, spacing, or radius) stored once and referenced everywhere. In Figma it's a Variable; in code it's a CSS variable like --primary. Change it once, everything bound to it updates.

A bound Figma variable is the exact twin of a CSS variable in globals.css. Set Aster's primary to oklch(0.55 0.24 285) once, and every instance bound to it retints - same as editing --primary in code.

61. Something is wrong here: 'a Figma variable is just a saved color swatch'

Anomaly

62. Trap: 'a Figma variable is just a saved color swatch'

Trap

63. Which of these survive contact with Session 1: Foundations & the Design-to-Code…?

Two truths and a lie

64. Variant vs boolean properties

Concept

Component properties in Figma come in kinds, and two matter today. A variant property swaps a whole style set; a boolean property toggles one feature on or off.

Use them the way code does. variant="outline" is a variant (many exclusive options). showIcon is a boolean (a single on/off). Booleans keep the variant set lean - you don't create a separate variant for 'with icon' and 'without icon'.

65. Fill in: Code twin for Variant vs boolean properties

Comparison

66. The Figma-to-code map

Concept

Here is the whole mental model in one table. Each Figma concept has exactly one code twin - that's what makes handoff a translation.

67. What has to happen first: Live in Figma: inspect a Button

Ranking

68. Live in Figma: inspect a Button

Worked example

Let's read a Button the way its code twin reads. Drop a Button instance on the canvas and open its properties on the right.

69. Work backwards from the answer: Live in Figma: inspect a Button

Reverse engineer

70. Answer it before you see the options: Check: what a bound variable does

Prediction

71. Check: what a bound variable does

Check

Every Aster button, badge, and link in the kit has its fill bound to the primary variable. You change primary from violet to teal, once, in the Variables panel.

72. Rule out three: Check: the code twin

Elimination

73. Check: the code twin

Check

You drag a Card from the Assets panel onto the Aster canvas. In code, what did you just do?

74. From Kit to Real Code

Section

Part 5 · The bridge

75. Responsive: same scale, more breakpoints

Concept

Aster's feature grid is one column on a phone and three on a desktop. In Tailwind that's grid-cols-1 md:grid-cols-3 - the md: prefix applies a class only at that breakpoint and up.

In Figma you plan this with breakpoints and constraints (pin / center / scale). The key discipline: keep spacing and type on the same scale across breakpoints, so the grid stays coherent.

76. Teach it back: Responsive: same scale, more breakpoints

Explain it

77. tweakcn - theme the kit visually

Concept

You won't hand-write OKLCH values from memory. tweakcn.com is a free visual theme editor for shadcn/ui: tune colors and radius, preview live, and export both a globals.css and a Figma-compatible theme.

That's the round trip you'll use for Aster next session: pick the violet and 0.625rem radius in tweakcn, export the tokens, and the same values drop into :root/.dark in code and into the Figma Variables panel. One source, both sides.

78. The scaffold you'll run later

Concept

No terminal today - but here's where this all lands. Next sessions you'll scaffold aster-site and pull components in; each command copies real source into components/ui/.

npx shadcn@latest init          # sets up config + globals.css
npx shadcn@latest add button card avatar badge input

Every part you place from the Figma kit today has a twin you'll add then own. The design work you're about to do IS the plan for that code.

79. By analogy: The scaffold you'll run later

Analogy

80. Your Turn: The Aster Profile Card

Section

Part 6 · Hands-on

81. The build: an Aster profile card

Concept

Time to build. You'll recreate a small Aster profile card entirely from kit parts - no terminal this session. The card shows a team member's avatar, name, an 'Available' badge, and a 'View work' button.

Four kit parts, assembled from the Assets panel. Do each milestone in Figma, then read the self-check to confirm you see the right thing before moving on.

82. Break it if you can: The build: an Aster profile card

Counterexample

83. Guess the shape of the answer: Milestone 1 - drop a Card frame

Estimation

84. Milestone 1 - drop a Card frame

Worked example

Your turn: place a Card from the kit as the container for everything else. Give it a moment - where in Figma do the kit's components live?

Hint: open the Assets panel (the component library) and find Card. You drag from there onto the canvas - you don't draw a rectangle by hand.

85. Work backwards from the answer: Milestone 1 - drop a Card frame

Reverse engineer

86. Guess the shape of the answer: Milestone 2 - add the Avatar

Estimation

87. Milestone 2 - add the Avatar

Worked example

Your turn: put an Avatar at the top of the card for the profile image. Which panel, again, holds the components?

Hint: back to the Assets panel - find Avatar and drag it inside the Card so it joins the card's Auto Layout.

88. What each one costs: Milestone 2 - add the Avatar

Trade off

89. Guess the shape of the answer: Milestone 3 - add the Badge

Estimation

90. Milestone 3 - add the Badge

Worked example

Your turn: add a Badge that reads 'Available' as a small status pill under the name. Same source as before.

Hint: drag Badge from the Assets panel, then use its variant property to pick the style, and edit its text to 'Available'.

91. Milestone 4 - add the Button

Worked example

Your turn: finish with a 'View work' Button at the bottom of the card. You know where to get it.

Hint: drag Button from the Assets panel; set its text to 'View work' and confirm its fill is bound to the primary variable so it wears Aster's violet.

92. Put it together

Worked example

Step back and look at the whole card. Four kit instances, stacked in the Card's Auto Layout, every color and radius coming from Aster's tokens.

If yours looks like this - a bordered card holding a circular avatar, a name, an 'Available' badge, and a violet button - you assembled a real UI from kit parts, and each part is the twin of a coded component.

93. Show it off - name the code twins

Worked example

Your turn: without touching code, explain how each kit part maps to a real coded component. Say it out loud, part by part - this is the fluency the whole series is building.

Hint: each Assets instance is an imported component; each variant/text you set is a prop; each bound fill is a token. Walk the card top to bottom.

That mapping - instance to component, property to prop, bound variable to token - is the design-to-code model in miniature. Everything in the coming sessions extends it.

94. Fill in: Its coded twin for Show it off - name the code twins

Comparison

95. Homework - the Aster component shortlist

Concept

Homework: browse the component gallery at ui.shadcn.com and get a feel for what's available - Button, Card, Input, Badge, Navigation Menu, and more.

Then write down the five components the Aster site will lean on most across its navbar, hero, feature grid, pricing, and footer. Think about what each section needs - for example a nav/navigation menu, a button, a card, an input, and a badge.

Bring that list to Session 2. It's the shopping list we'll use when we start theming and, eventually, scaffolding the real aster-site project.

96. Connect it up: Session 1: Foundations & the Design-to-Code Mental Model

Connect it up

97. What you can do now

Recap

• Explain the three layers: Tailwind is utility-first styling (paint), Radix is headless behavior + accessibility (skeleton), shadcn/ui is the assembled component you own.
• Say why shadcn is copied into your repo (components/ui/) and owned - full control, no lock-in, updates on your terms - unlike an installed closed library.
• Route any decision with the 'which layer owns this?' recipe: behavior to Radix, utility styling/token to Tailwind, the assembled component to shadcn.
• Navigate the Figma kit - Pages, Assets panel, Variables panel - and map each to its code twin.

Next time (Session 2): design tokens in depth - primitive to semantic to mode, OKLCH, and wiring Aster's violet through :root, .dark, and @theme inline so one variable retints the whole site.