# @9klabs/design

> Vue 3 components, design tokens and guidance for the 9k products. Every page of this site is also available as Markdown at its URL plus `.md`.

Install with `npm install @9klabs/design` and import `@9klabs/design/style.css` once at the app entry.
The whole site in one file is https://design.the9klabs.com/llms-full.txt, and every component's API as JSON is https://design.the9klabs.com/components.json.

## Rules

- I9kInput names its visual scale prop `uiSize`, not `size`, so the native HTML `size` attribute stays available on the underlying input.
- Every component owns its appearance in `<style scoped>` and must not rely on global classes for its look.
- Components declare component-local custom properties on their root class and redefine them per size modifier, rather than consuming raw brand tokens for sizing.
- Sizes and tones come from the shared `I9kComponentSize` and `I9kTone` types. Do not redeclare those string unions per component.
- I9kButton renders a `<button>`, an `<a>`, or a caller-supplied component: pass `to` or `href` for a link, and `link-component="RouterLink"` in Vue Router apps.
- I9kIcon renders from the local `src/icons/paths.json` set. Add new icons to that file rather than inlining SVG in a component.
- Components emit legacy classes alongside their `i9k-` ones while the website migration is in progress. Do not remove a legacy selector or prop until its migration ledger row is complete.
- Import the stylesheet once, at the application entry: `@9klabs/design/style.css`. It is the only CSS a consumer needs.
- Any visual change needs checking in light and dark themes and in both LTR and RTL directions.

## Getting started

- [Installation](https://design.the9klabs.com/getting-started/installation.md): Install @9klabs/design, import its one stylesheet, load the brand fonts, and render your first component.
- [Vue Router and Nuxt](https://design.the9klabs.com/getting-started/frameworks.md): Route links through Vue Router or Nuxt, install the toaster per app, and keep server rendering safe.
- [Working with AI agents](https://design.the9klabs.com/getting-started/ai-agents.md): Point Claude or any coding agent at these docs. Every page is Markdown at its URL plus .md, llms.txt indexes them, and each component has a self-contained prompt.

## Foundations

- [Design tokens](https://design.the9klabs.com/foundations/tokens.md): The colors, spacing, radii, control sizes and page measures every component is built from, read straight from tokens.css.
- [Sizes](https://design.the9klabs.com/foundations/sizes.md): One sm, md and lg scale for every control, so buttons, inputs and badges of the same size line up.
- [Theming and dark mode](https://design.the9klabs.com/foundations/theming.md): Switch between light and dark with one class on the html element, remember the reader's choice, and make your own components follow.
- [Arabic and right-to-left](https://design.the9klabs.com/foundations/rtl-and-arabic.md): Mark Arabic content with lang and dir. The components mirror on their own and take the Arabic typefaces from the language.
- [Page layout](https://design.the9klabs.com/foundations/layout.md): One page column shared by the navigation, every section and the footer, plus the grid, cluster and panel that arrange content inside it.

## Guides

- [Notifications and dialogs](https://design.the9klabs.com/guides/notifications-and-dialogs.md): Raise toasts from one per-app toaster, interrupt with a modal, and let the two work together without lost or repeated announcements.
- [Building a component](https://design.the9klabs.com/guides/building-a-component.md): The conventions a new component in @9klabs/design follows, from scoped styles and the size scale to its registry entry and tests, with a prompt that teaches them to an agent.
- [Rules for agents](https://design.the9klabs.com/guides/rules-for-agents.md): The constraints every component follows that a props table cannot express. Agents should read these before writing UI with the design system.

## Components

- [Components](https://design.the9klabs.com/components.md): Every one of the 61 components in @9klabs/design, by purpose.

## Layout & surfaces

- [I9kContainer](https://design.the9klabs.com/components/container.md): The page column: a centred, width-capped wrapper that sets only width and centring, so a section, a main or a bar of chrome all share one measure. I9kNavigation, I9kFooter and I9kPageContainer already sit in it.
- [I9kGrid](https://design.the9klabs.com/components/grid.md): CSS grid layout wrapper with a fixed 1/2/3-column or auto-filling track and a size-driven gap. Collapses to one column on narrow viewports.
- [I9kPageContainer](https://design.the9klabs.com/components/page-container.md): Centered, width-capped page wrapper with a size-driven horizontal gutter and a minimum height, in the shared page column. Use it once per page as the outermost content wrapper; for a section of a page use I9kContainer.
- [I9kCluster](https://design.the9klabs.com/components/cluster.md): Flex-wrap row that keeps items center-aligned and evenly gapped, wrapping onto new lines instead of overflowing. Use it for groups of buttons, badges, or other inline controls.
- [I9kPanel](https://design.the9klabs.com/components/panel.md): Opaque, bordered surface for grouping content. Use it as the standard card/surface wrapper wherever content needs visual separation from the page background.

## Content

- [I9kText](https://design.the9klabs.com/components/text.md): Text primitive for body copy and intros. Use it for any paragraph-level content that should follow the design system type scale rather than reaching for a bare <p>.
- [I9kSectionHeading](https://design.the9klabs.com/components/section-heading.md): Heading with an optional description for introducing a section of a page. Use it above any grouped block of content — a card grid, a list, a feature set.
- [I9kPageHeader](https://design.the9klabs.com/components/page-header.md): Large hero-style heading for the top of a page, with optional subtitle, description, actions, and avatar. Use it once per page, at the top.
- [I9kArticleHeader](https://design.the9klabs.com/components/article-header.md): Wide banner image for the top of an article, with a generated watermark fallback when there is no image. Use it once, at the top of an article body.
- [I9kBadge](https://design.the9klabs.com/components/badge.md): Small inline label for status, category, or tag content. Use it next to a heading or inside a card to mark a short piece of metadata.
- [I9kStat](https://design.the9klabs.com/components/stat.md): Value/label/source stack for a single statistic. Use it in a grid of a few key numbers, such as metrics on an about page or a pricing comparison.
- [I9kLevelMeter](https://design.the9klabs.com/components/level-meter.md): A short row of rising steps with some filled, for a level out of a few, such as a course level. It is a named meter, the level can be shown in words beside it, and a description can explain it in a tooltip.
- [I9kSticker](https://design.the9klabs.com/components/sticker.md): A die-cut sticker with a holographic foil that follows the pointer, for a badge a person has earned. The foil is drawn over the sticker image and clipped to its shape; it stands still for people who prefer reduced motion.
- [I9kLinkCard](https://design.the9klabs.com/components/link-card.md): Clickable card linking out to an external resource, with a name, description, and optional image/badge/arrow. Use it for a grid of projects, articles, or external links.
- [I9kTimelineCard](https://design.the9klabs.com/components/timeline-card.md): Dated entry in a vertical timeline/rail, with a title, body, and optional thumbnail. Use it for a chronological list of talks, posts, or events.
- [I9kProfileCard](https://design.the9klabs.com/components/profile-card.md): Card pairing an avatar with a name, bio, and optional action links. Use it for an author byline, a team member card, or a speaker bio.
- [I9kAvatar](https://design.the9klabs.com/components/avatar.md): A round picture of a person or account from any image URL, with a fallback slot (such as initials) for when there is no picture.
- [I9kBandanaAvatar](https://design.the9klabs.com/components/bandana-avatar.md): A large round photo of a person with a bandana that draws itself across the eyes, once when the images load and again when a pointer enters. The bandana never shows for people who prefer reduced motion.
- [I9kCollapsible](https://design.the9klabs.com/components/collapsible.md): Native, independently expanding disclosure surface with slots for rich summary and body content.
- [I9kSection](https://design.the9klabs.com/components/section.md): Titled page section, named by its heading, whose header carries its own actions and an optional toolbar. It can collapse behind a disclosure button inside the heading, controlled with v-model:open or left to manage itself. The primary variant fills it with the brand green, and fullWidth lets that fill reach the viewport edges as a band.
- [I9kFaqList](https://design.the9klabs.com/components/faq-list.md): List of collapsible question/answer pairs composed from I9kCollapsible. Use it for plain-text FAQ content without wiring open/close state.
- [I9kGithubEmbed](https://design.the9klabs.com/components/github-embed.md): Compact card linking to a GitHub repository by "owner/repo" name. Use it to reference a specific repo inline in content, e.g. a blog post or project list.
- [I9kIcon](https://design.the9klabs.com/components/icon.md): SVG icon rendered from the library's built-in icon set by name. Use it anywhere a small inline glyph is needed — social links, nav items, buttons.
- [I9kAsciiEmoji](https://design.the9klabs.com/components/ascii-emoji.md): Small text-based emoticon (e.g. "^_^") rendered in a monospace face, for a lighter-touch alternative to emoji or icon glyphs.
- [I9kNino](https://design.the9klabs.com/components/nino.md): Nino, the 9k pixel mascot: an inline-SVG character with eight expressions (one of them hide and seek, one dizzy), continuous ambient life (breathing, blinks, an antenna pulse, idle glances), a 300ms face morph on mood changes, one-shot actions (wave, jump, nod, shake, dizzy), a talking state, a logical gaze direction, and motion that switches itself off for reduced-motion visitors.
- [I9kNinoMaze](https://design.the9klabs.com/components/nino-maze.md): A small game for a 404 page: walk Nino through a pixel maze to his house while bugs patrol the corridors. Every seed builds one maze, the same seed always builds the same maze, and every maze is checked to be winnable. Keyboard, d-pad and screen-reader playable, with optional chiptune sound.
- [I9kNinoSky](https://design.the9klabs.com/components/nino-sky.md): A pixel night sky with Nino drifting through it: twinkling dotted stars, two dotted planets, eyes that follow the pointer, a boop (a new face, a spin and a burst of sparkles) on click, tap, Enter or Space, and a drag: pick Nino up, throw him around the window, and if he comes to rest above the sky he swoops back to it, dizzy. It has no background of its own and follows the page theme. Made for the space under a footer.
- [I9kChat](https://design.the9klabs.com/components/chat.md): The shell of a scripted chat: a feature panel with a header (Nino, the bot name and actions), a scrolling live log of bubbles, and a sunken footer tray for the answer controls.
- [I9kChatBubble](https://design.the9klabs.com/components/chat-bubble.md): One message in an I9kChat log: a bot bubble on the start side or a user bubble on the end side, with a typing indicator, a wide variant for rich results and an editable variant for revisiting an answer.

## Forms

- [I9kChatComposer](https://design.the9klabs.com/components/chat-composer.md): The free-text answer of an I9kChat footer: a rounded field with a send button. Enter sends; a multiline composer grows with the text and takes Shift+Enter for a new line.
- [I9kField](https://design.the9klabs.com/components/field.md): Field wrapper that renders a label, hint, and error, and provides id/size/validity context to one nested control. It is the provider side of the field composable; I9kInput, I9kTextarea, and I9kSelect are its consumers.
- [I9kCheckboxGroup](https://design.the9klabs.com/components/checkbox-group.md): Accessible checkbox fieldset for selecting multiple values with labels, descriptions, validation, and RTL support.
- [I9kInput](https://design.the9klabs.com/components/input.md): Single-line text input with an optional label, hint, and error state. Wires its own accessible ids, and inherits size and error state from a wrapping I9kField when there is one.
- [I9kTextarea](https://design.the9klabs.com/components/textarea.md): Multi-line text control for longer form input. Wires its own id and ARIA attributes standalone, and inherits id, size, and error state from a wrapping I9kField when there is one.
- [I9kSelect](https://design.the9klabs.com/components/select.md): Native single-select dropdown that auto-selects the option matching modelValue. Wires its own id and ARIA attributes standalone, and inherits id, size, and error state from a wrapping I9kField when there is one.
- [I9kPhoneInput](https://design.the9klabs.com/components/phone-input.md): Phone number input with a compact country-code picker: a flag-and-code face over a transparent native select that lists every country by name. Registers the number, not the picker, with a wrapping I9kField.
- [I9kRadioGroup](https://design.the9klabs.com/components/radio-group.md): Fieldset of mutually exclusive radio options, rendered as a stacked list or a card grid. Unlike I9kInput, I9kTextarea, and I9kSelect, it does not participate in the I9kField composable — it owns its own legend, hint, error, and ids entirely.

## Actions

- [I9kChatOptions](https://design.the9klabs.com/components/chat-options.md): The answer row of an I9kChat footer: a named group of reply buttons aligned to the user side, with a focus() handle so the conversation can move focus to the next question.
- [I9kButton](https://design.the9klabs.com/components/button.md): Polymorphic action trigger: renders a native button by default, an anchor when given a destination, or a caller-supplied component. Six variants cover primary actions, filters, and pagination.
- [I9kButtonGroup](https://design.the9klabs.com/components/button-group.md): Layout wrapper that spaces a row or column of buttons with a consistent gap and groups them as one control for assistive tech.
- [I9kIconButton](https://design.the9klabs.com/components/icon-button.md): Circular icon-only action trigger: renders a native button by default, or an anchor/caller-supplied component when given a destination. Its own variant set is separate from I9kButton.
- [I9kTabs](https://design.the9klabs.com/components/tabs.md): Accessible horizontal tabs (the WAI-ARIA tabs pattern with automatic activation): a named tablist of equal-width tabs over the one panel that belongs to the selected tab.

## Feedback

- [I9kToast](https://design.the9klabs.com/components/toast.md): Styled, accessible message banner for standing status or error text in the page flow. For notifications (saved, failed, sent), use I9kToaster, which renders I9kToast for each one.
- [I9kToaster](https://design.the9klabs.com/components/toaster.md): The one place notifications appear: a fixed stack at the top of the viewport that shows the toasts raised through a per-app store, announces each through its own live regions, dismisses info and success after five seconds and keeps warnings and errors until the user dismisses them.
- [I9kTooltip](https://design.the9klabs.com/components/tooltip.md): A short plain-text note above an element, shown on hover, keyboard focus or tap. It also describes the element to assistive technology.
- [I9kModal](https://design.the9klabs.com/components/modal.md): Accessible modal dialog built on the native <dialog> element, labelled by its title, with a close button, a scrolling body, and an optional footer. The parent owns whether it is open.

## Site chrome

- [I9kAskAi](https://design.the9klabs.com/components/ask-ai.md): A heading and a row of pill links that open ChatGPT, Perplexity and Claude in a new tab with a question about the site already typed in.
- [I9kAnnouncementBar](https://design.the9klabs.com/components/announcement-bar.md): Full-bleed brand-green bar for one short site-wide message, an optional link and a close button, laid out in the shared page column. Placed above I9kNavigation. Stateless: it emits close and the consumer hides it.
- [I9kNavigation](https://design.the9klabs.com/components/navigation.md): Sticky site header with a brand slot, a link list, and an actions slot, laid out in the shared page column. Tracks scroll position to add a background on scroll and switch the brand into a compact state. Renders plain anchors, or a caller-supplied router link component.
- [I9kNavMenu](https://design.the9klabs.com/components/nav-menu.md): Mobile navigation: a bars toggle that opens a full-screen panel with the brand, the link list, and a footer slot. Owns the modal behavior — teleport, scroll lock, focus trap, Escape, and closing itself when the viewport passes the desktop breakpoint.
- [I9kProfileMenu](https://design.the9klabs.com/components/profile-menu.md): The signed-in account's control for a navigation bar: an avatar button that opens a small panel naming the account, its links and the caller's actions, such as signing out.
- [I9kBreadcrumb](https://design.the9klabs.com/components/breadcrumb.md): A breadcrumb trail in a named navigation landmark: every step but the last links back, and the last is the current page.
- [I9kSidebarLayout](https://design.the9klabs.com/components/sidebar-layout.md): A full-height frame: a slim sticky bar, a sidebar and a main area. Wide screens show the sidebar as a column the reader can hide; narrow screens open it as a modal drawer from the bar.
- [I9kSideNav](https://design.the9klabs.com/components/side-nav.md): An app sidebar's section links: a labelled navigation landmark holding a vertical list, with the current section marked, and a footer slot below the list.
- [I9kFooter](https://design.the9klabs.com/components/footer.md): A page's bottom chrome. On its own it is a centred row of social links and a tagline; given link columns or a brand it becomes a multi-column site footer with a bottom bar.
- [I9kBrandWordmark](https://design.the9klabs.com/components/brand-wordmark.md): Decorative, self-animating logotype that types itself out and swaps between a full and short form — purely visual, and carries no accessible name of its own.
- [I9kSocialLinks](https://design.the9klabs.com/components/social-links.md): Row of pill-shaped social/contact links, each opening in a new tab, with an icon fallback and a customizable accessible label per item.
- [I9kThemeSwitcher](https://design.the9klabs.com/components/theme-switcher.md): Controlled light/dark icon button. It renders and emits the toggle only — applying the theme to the page is entirely the caller's job.
- [I9kLanguageSwitcher](https://design.the9klabs.com/components/language-switcher.md): A link to an alternate-language version of the current page, shown as a compact glyph-plus-locale-code button. It is only the link's markup — it does not itself switch the page's language or navigate via JS.
- [I9kBlurredCircles](https://design.the9klabs.com/components/blurred-circles.md): Decorative, non-interactive layer of four slow-drifting blurred circles, meant as an ambient page background sitting behind real content.
- [I9kGlow](https://design.the9klabs.com/components/glow.md): Decorative, non-interactive page background: one large, soft, film-grained glow in the brand green, amber, and orange, half off-screen at an edge or corner, drifting slowly.