Plain English Styling

Natural language styling is Taildown's superpower. Write {large-bold primary} instead of cryptic CSS classes.

Philosophy

Natural Grammar First

Taildown follows natural English grammar and word order, not CSS conventions. This makes styling intuitive and self-documenting.

Core Principles:

Adjective-Noun Order - "large text" not "text-large"
Single Descriptive Words - "bold" not "font-bold"
State Modifiers First - "hover-lift" not "lift-hover"
Natural Phrases - Reads like English, compiles to CSS

Typography

Sizes

Control text size with natural keywords:

Unstyled reading text scales from 16px to 18px with the viewport. Headings retain their semantic size hierarchy and use compact line spacing. Explicit size and line-height attributes override these defaults.

Inline code uses a readable text/background pair in both themes, including inside tables and tooltips. Customize --inline-code-text and --inline-code-background in your CSS when composing a different palette; fenced code retains its syntax-highlighting theme.

Shorthand	Result	CSS Equivalent
`{xs}`	Extra small text	`text-xs`
`{small}`	Small text	`text-sm`
`{base}`	Base size (default)	`text-base`
`{large}`	Large text	`text-lg`
`{xl}`	Extra large text	`text-xl`
`{2xl}`	2X large text	`text-2xl`
`{3xl}`	3X large text	`text-3xl`
`{huge}`	Huge text	`text-4xl`
`{massive}`	Massive text	`text-6xl`

Examples:

# Huge Heading {huge}
Normal paragraph text {base}
Small footnote {small muted}

Font families

Shorthand	Family	CSS Equivalent
`{sans}`	Sans-serif	`font-sans`
`{serif}`	Serif	`font-serif`
`{mono}`	Monospace	`font-mono`

These use the document's font stacks. Set theme.fonts in the compiler API to override the stacks; font files are not downloaded automatically. The editor exposes all three in style completion and the Insert / Ctrl/Cmd+K menu.

A considered idea

A clear instruction

const idea = 'make it readable';

Weights

Control font weight naturally:

Shorthand	Result	CSS Equivalent
`{thin}`	Thin weight	`font-thin`
`{light}`	Light weight	`font-light`
`{normal}`	Normal weight	`font-normal`
`{medium}`	Medium weight	`font-medium`
`{semibold}`	Semi-bold	`font-semibold`
`{bold}`	Bold weight	`font-bold`
`{extra-bold}`	Extra bold	`font-extrabold`
`{black}`	Black weight	`font-black`

Examples:

# Bold Heading {bold}
Semibold emphasis {semibold primary}
Light muted text {light muted}

Combinations

Combine size and weight naturally:

Use the listed compound shorthands or separate tokens, such as {xl bold}. medium means font weight, so use {bold} for a bold heading at its natural size rather than the unsupported medium-bold.

# Large Bold Title {large-bold primary}
Medium weight subheading {medium}
Small light muted text {small-light muted}

Common combinations:

{large-bold} - Large and bold
{huge-bold} - Huge and bold
{small-light} - Small and light
{xl-semibold} - XL and semi-bold

Line Height

Control line spacing with natural phrases:

Shorthand	Result
`{tight-lines}`	Tight line spacing
`{normal-lines}`	Normal spacing (default)
`{relaxed-lines}`	Relaxed spacing
`{loose-lines}`	Loose spacing

Example:

Paragraph with tight lines {tight-lines}
Paragraph with relaxed lines {relaxed-lines}

Colors

Semantic Colors

success, warning, error, and info use separate text colors for light and dark pages. Customize --success-text (and the corresponding status variables) independently of the background --success and its --success-foreground. Explicit numbered utilities keep their fixed shades.

muted and combinations such as small-muted use the theme's --muted-foreground, keeping supporting text readable in both themes. Use a numbered gray utility when you specifically want a fixed shade.

primary, secondary, and accent text colors follow the active light or dark theme, including their hover shades. Use these semantic names for readable accents on the default page and card surfaces. Explicit numbered utilities such as text-primary-600 keep their fixed shade. Custom CSS can tune --primary-text and --primary-text-hover (and the corresponding secondary/accent variables) independently of button and background colors.

Use semantic color names for consistency:

Color	Usage	Example
`primary`	Primary brand color	Primary
`secondary`	Secondary brand color	Secondary
`accent`	Accent highlights	Accent
`success`	Success states	Success
`warning`	Warning states	Warning
`error`	Error states	Error
`info`	Information	Info
`muted`	Muted/subtle text	Muted

Examples:

# Primary Heading {primary}
Success message {success}
Error alert {error bold}
Muted footer text {muted small}

Background Colors

Add -bg suffix for background colors. Status pairs use the same theme colors and contrasting foregrounds as status buttons:

Shorthand	Result
`{primary-bg}`	Primary background + white text
`{success-bg}`	Success background + contrasting text
`{warning-bg}`	Warning background + dark text
`{error-bg}`	Error background + contrasting text
`{muted-bg}`	Muted background + dark text

Examples:

:::card {primary-bg}
Primary colored card
:::

:::alert {success-bg}
Success message with background
:::

Layout

Flex

Flexible layout with natural syntax:

Shorthand	Result
`{flex}`	Flex container
`{flex-col}`	Flex column direction
`{flex-row}`	Flex row direction
`{flex-center}`	Flex with centered items
`{flex-wrap}`	Flex with wrapping

Example:

:::card {flex flex-center}
Centered content
:::

Grid

Grid layouts made simple:

Shorthand	Result
`{grid}`	Grid container
`{grid-2}`	2-column grid
`{grid-3}`	3-column grid
`{grid-4}`	4-column grid
`{grid-auto}`	Auto-fit grid

Example:

:::grid {3}
Three column grid
:::

Centering

Center elements naturally:

Shorthand	Result
`{center}`	Center text
`{center-x}`	Center horizontally
`{center-y}`	Center vertically
`{center-both}`	Center both directions

Example:

# Centered Heading {center}
:::card {center-both}
Fully centered card
:::

Spacing

Padding

Control internal spacing:

Shorthand	Size
`{padded-xs}`	Extra small padding
`{padded-sm}`	Small padding
`{padded}`	Default padding
`{padded-lg}`	Large padding
`{padded-xl}`	Extra large padding

Example:

:::card {padded-lg}
Large padded card
:::

Gap

Control spacing between items:

Shorthand	Size
`{gap-xs}`	Extra small gap
`{gap-sm}`	Small gap
`{gap}`	Default gap
`{gap-lg}`	Large gap
`{gap-xl}`	Extra large gap

Example:

:::grid {3 gap-lg}
Grid with large gaps
:::

Effects

Borders & Corners

Rounded corners and borders:

Shorthand	Result
`{rounded}`	Default rounded corners
`{rounded-sm}`	Small rounded corners
`{rounded-lg}`	Large rounded corners
`{rounded-xl}`	Extra large rounded
`{rounded-full}`	Fully rounded (circle/pill)

Example:

:::card {rounded-xl}
Extra rounded card
:::

[Pill Button](#){button primary rounded-full}

Shadows

Add depth with shadows:

Shorthand	Result
`{shadow}`	Default shadow
`{shadow-sm}`	Small shadow
`{shadow-lg}`	Large shadow
`{shadow-xl}`	Extra large shadow
`{elevated}`	Elevated appearance
`{floating}`	Floating effect

Example:

:::card {elevated}
Elevated card
:::

:::card {shadow-xl}
Deep shadow card
:::

Glassmorphism

Frosted glass effects:

Shorthand	Transparency	Use Case
`{subtle-glass}`	90%	Very subtle
`{light-glass}`	75%	Light frosted
`{glass}`	60%	Standard glass
`{heavy-glass}`	40%	Heavy frosted

Example:

:::card {light-glass}
Light frosted glass card
:::

:::card {heavy-glass padded-xl}
Heavy frosted with padding
:::

Animations

Entrance

Scroll-triggered entrance animations:

{fade-in} - Fade in
{slide-up} - Slide up
{slide-down} - Slide down
{slide-left} - Slide left
{slide-right} - Slide right
{zoom-in} - Zoom in
{zoom-out} - Zoom out

This card has {fade-in} applied!

Hover Effects

Interactive hover animations:

{hover-lift} - Lift on hover
{hover-glow} - Glow on hover
{hover-scale} - Scale up on hover
{hover-rotate} - Rotate on hover
{hover-grow} - Grow on hover

This card has {slide-up} applied!

Speed

Control animation speed:

{fast} - Fast animations (150ms)
{smooth} - Smooth (300ms, default)
{slow} - Slow animations (500ms)

This card has {zoom-in} applied!

Combining Shorthands

The Power of Composition

Taildown shorthands combine naturally to create complex styles with readable syntax.

Simple Example

# Heading {large-bold primary center}

Combines:

large - Large text size
bold - Bold font weight
primary - Primary color
center - Centered alignment

Complex Example

:::card {light-glass padded-xl rounded-xl hover-lift fade-in}
Card content
:::

Combines:

light-glass - Frosted glass effect
padded-xl - Extra large padding
rounded-xl - Extra large corners
hover-lift - Lift on hover
fade-in - Entrance animation

Best Practices

Do

Use natural English word order
Combine shorthands for rich effects
Keep it readable and self-documenting
Use semantic color names
Leverage glassmorphism for modern looks
Add hover effects for interactivity

# Great Title {huge-bold primary center}

:::card {light-glass padded-lg hover-lift}
Beautiful, readable, and powerful!
:::

Don't

Don't use CSS property names
Don't reverse natural word order
Don't overuse effects
Don't hardcode colors
Don't ignore semantic meaning

# Bad Title {.text-4xl .font-bold .text-blue-500}

:::card {.bg-white .p-8}
Falls back to raw CSS classes
:::

Color transparency

For neutral surfaces, gray provides a neutral scale and slate a cooler blue-gray scale. Both have shades 50, 100 through 900 in steps of 100, and 950. Use text-slate-900, bg-slate-50, or border-slate-200, with dark variants for an alternate theme. Semantic muted text adapts automatically when you want a readable secondary text color.

Add an integer opacity from 0 to 100 after a color utility: bg-primary/20, text-gray-900/80, or border-primary/30. This changes that color rather than fading the element's children. It also works with configured colors and prefixes such as dark:bg-primary/10 or md:bg-primary/20.

Styling dark mode

Semantic colors adapt automatically. For a deliberate palette in each theme, prefix a utility with dark:. The rule applies while the document's dark-mode toggle is active, including in exported HTML.

Dark variants compose with hover:, active:, focus:, focus-visible:, disabled:, last:, and the sm:, md:, lg:, xl:, 2xl: breakpoints. Use utility names after the prefix, such as dark:text-gray-100. In the editor, search Dark mode colors in the Insert menu to start with an editable example.

Quick Reference Card

Cheat Sheet

Typography: xs small large xl 2xl 3xl huge massive | thin light normal medium semibold bold extra-bold black

Colors: primary secondary accent success warning error info muted

Layout: flex flex-col flex-row flex-center | grid grid-2 grid-3 grid-4 | center center-x center-y

Spacing: padded-xs padded-sm padded padded-lg padded-xl | gap-xs gap-sm gap gap-lg gap-xl

Effects: rounded rounded-sm rounded-lg rounded-xl rounded-full | shadow shadow-sm shadow-lg elevated floating

Glass: subtle-glass light-glass glass heavy-glass

Animations: fade-in slide-up slide-down zoom-in | hover-lift hover-glow hover-scale | fast smooth slow

Plain English Reference

Philosophy

Natural Grammar First

Typography

Sizes

Font families

Weights

Combinations

Line Height

Colors

Semantic Colors

Background Colors

Layout

Flex

Grid

Centering

Spacing

Padding

Gap

Effects

Borders & Corners

Shadows

Glassmorphism

Animations

Entrance

Hover Effects

Speed

Combining Shorthands

The Power of Composition

Best Practices

Do

Don't

Color transparency

Styling dark mode

Quick Reference Card

Cheat Sheet