Luau Design System

Luau (lowercase u, /ˈlu.aʊ/) is a small, fast, and embeddable programming language built by Roblox, based on Lua 5.1 with a gradual type system. The language powers Roblox's game scripting platform and is open-source at github.com/luau-lang/luau. The mascot is Hina, a Hawaiian monk seal.

Sources Provided

Source	Path/URL
Website codebase	site/ (mounted — Astro/Starlight)
Logo SVG	assets/luau-logo.svg
Mascot PNG	assets/mascot.png
Font files	fonts/ — Builder Sans + Builder Mono
Repo (GitHub)	https://github.com/luau-lang/site

---

Products / Surfaces

Surface	Description
Marketing/Docs site	luau.org — Astro + Starlight dark-first docs site with a custom homepage. Sections: Getting Started, Advanced Users, Type System, Reference, News.
Playground	play.luau.org — interactive Luau code editor embedded as an iframe.

---

CONTENT FUNDAMENTALS

Tone & Voice

• Confident and technically precise, but warm. The writing treats readers as capable engineers. It explains why decisions were made, not just what they are.
• First-person plural ("we don't believe it makes sense", "we love this, but it breaks compatibility"). Team voice — approachable, collaborative, never corporate.
• Casual candor. Phrases like "there be dragons", "suboptimal", "not beautiful" appear in technical docs. No stuffiness.
• Human-warmth in feature copy. "aims to be pleasant and productive… programming as fun as it can be" — unusual warmth for a language spec site.

Casing

• Sentence case for all headings and UI labels (not Title Case).
• The language name is always Luau (capital L, lowercase u). Never LUAU.

Emoji

• Used sparingly and purposefully in technical content (🤷 in compatibility tables). Not decorative.
• The "meowluau" image (blob cat holding the logo) is used as a footer tagline — playful brand moment.

Examples of Good Copy

"Luau is a high-performance managed language with a fast bytecode compiler and interpreter…" "we do not always agree with Lua design decisions" "Luau aims to be pleasant and productive to use, and to make programming as fun as it can be!"

---

VISUAL FOUNDATIONS

Colors

• Dark-first. Default background is #000000. Light mode uses --color-gray-100/#EEEFF1 for bg.
• Accent blue #335FFF (accent-500/600) — links, active nav, interactive highlights. Scale runs from #335EFD (accent-50) to #112056 (accent-950).
• Neutral grays — cool-tinted scale from #F7F7F8 (gray-50) to #191A1F (gray-950).
• Extended palette — 14-step scales for blue, green, red, orange, yellow, purple, magenta, pink, turquoise. Used for card accent backgrounds.

Typography

• Sans: Builder Sans (Roblox brand font, weights 100–800 + italics), fallback Arial. Used for all body/UI text.
• Mono: Builder Mono (weights 300/400/700), used for code. Ligatures explicitly disabled.
• Headings: font-weight: 800 (ExtraBold) — strong, assertive. Card titles: 600–800. Body: 400–500.
• Line height: 1.6 for body prose.

Spacing

• Card padding: clamp(1rem, calc(0.125rem + 3vw), 2.5rem) — fluid, never cramped.
• Card gaps: clamp(0.5rem, calc(0.125rem + 1vw), 1rem).
• Nav height: --sl-nav-height shared by nav, header, footer.
• Blog gap: 1.25rem between posts, 2rem between intro and list.
• Documentation density — spacious but purposeful, not marketing-site airy.

Corner Radii

• Cards: border-radius: 0.5em
• Icon chips (inside cards): border-radius: 0.25rem
• Link cards: border-radius: 0.5rem
• Nothing pill-shaped — corners softened but angular enough to feel technical.

Card System

• Cards use a 4-accent rotation via CSS :nth-child — purple → orange → green → red — giving card grids automatic visual variety without per-card theming.
• ColoredCard uses full colored backgrounds (card-bg-{color}). BetterCard uses dark base with colored border/icon-chip accents.
• Icon chips: small square containers with 1px colored border + colored bg, 0.25rem radius. Color matches the card accent.
• On hover: icon chip flips colors (bg↔border), card border tightens.

Backgrounds & Surfaces

• Pure black (#000) default background. No gradients on main surfaces.
• Cards sit on black with 1px solid var(--gray-5) borders — subtle depth via border, not shadow.
• var(--sl-color-hairline-shade) (--color-gray-800 / dark) for nav/sidebar dividers.
• No background images, patterns, or textures on main layout.
• Light mode: layered gray surfaces (100/200/300 for bg/sidebar/nav).

Animation & Hover States

• Nav links: color change to --sl-color-text-accent on hover — no transform or opacity.
• Link cards: background changes to --sl-color-gray-7 on hover, border brightens.
• Card icon chips: border/bg swap on hover.
• No bounce, spring, or elaborate motion. Subtle color transitions only.
• No explicit transition durations defined in the codebase — browser defaults.

Borders & Shadows

• 1px solid borders throughout. No outer drop shadows on cards.
• var(--sl-shadow-sm) used on link cards only.
• No inner shadows.

Imagery

• Mascot (Hina): Blue Hawaiian monk seal. Cartoon style, black outline. Used prominently on homepage hero.
• meowluau: Blob cat emoji holding the Luau logo — footer easter egg.
• Screenshots: Used in news/blog posts for UI/debugging examples.
• No full-bleed hero images. No grain, warm/cool toning, or b&w treatment.

Iconography

See ICONOGRAPHY section below.

---

ICONOGRAPHY

• Icons come from @astrojs/starlight's built-in icon set — used via <Icon name="..." /> component.
• Starlight icons are SVG-based, inline. Stroke-weight is consistent with the text.
• Icons seen in use: rocket, approve-check-circle, pen, sun, puzzle, setting, right-arrow, left-arrow, up-arrow, down-arrow, right-caret, github, rss.
• No custom icon font or sprite sheet — Starlight icons only.
• No emoji used as icons in UI (only sparingly in markdown content).
• Unicode chars not used as icons.
• The logo (luau-logo.svg) is a white square embedded in a blue square on a 15° tilt with "Luau" text. Available at assets/luau-logo.svg and assets/luau-logo-src.svg.
• assets/favicon.svg — favicon version.
• assets/chess-profile.svg — decorative image used in playground/news context.

Key assets copied:

• assets/luau-logo.svg — main logo
• assets/luau-logo-src.svg — source logo from Astro assets
• assets/mascot.png — Hina the seal
• assets/meowluau.png — blob cat footer element
• assets/chess-profile.svg
• assets/favicon.svg

For UI kit use: Starlight icons are not available outside the Astro build. UI kits substitute with inline SVGs or similar placeholders — see ui_kits/site/ for the approach used.

---

File Index

/
├── README.md                  — this file
├── SKILL.md                   — agent skill descriptor
├── colors_and_type.css        — CSS custom properties: colors, type scale, semantic tokens
├── fonts/
│   ├── font-face.css          — @font-face declarations (relative paths)
│   ├── BuilderSans-*.woff2    — Builder Sans weights 100–800 + italics
│   └── BuilderMono-*.woff2    — Builder Mono weights 300/400/700
├── assets/
│   ├── luau-logo.svg          — main Luau logo
│   ├── luau-logo-src.svg      — Astro source version
│   ├── mascot.png             — Hina the Hawaiian monk seal
│   ├── meowluau.png           — blob cat footer element
│   ├── chess-profile.svg      — decorative chess profile image
│   └── favicon.svg            — site favicon
├── preview/                   — Design System tab cards (small HTML specimens)
│   ├── colors-accent.html
│   ├── colors-grays.html
│   ├── colors-extended.html
│   ├── colors-semantic.html
│   ├── type-sans-scale.html
│   ├── type-weights.html
│   ├── type-mono.html
│   ├── spacing-tokens.html
│   ├── spacing-radii.html
│   ├── components-cards.html
│   ├── components-linkcard.html
│   ├── components-nav.html
│   ├── brand-logo.html
│   └── brand-mascot.html
└── ui_kits/
    └── site/
        ├── README.md
        ├── index.html         — interactive site prototype
        ├── Header.jsx
        ├── Footer.jsx
        ├── ColoredCard.jsx
        ├── BetterCard.jsx
        ├── Sidebar.jsx
        └── DocPage.jsx