# Kontenedor — rules for AI agents - Use semantic Tailwind tokens (bg-background, text-foreground, bg-surface, bg-muted, text-muted-foreground, border-border, bg-primary, text-primary-foreground, bg-success-subtle…). Never hard-code hex colors. - Use border-k (not border) so borders follow the weight; use focus-ring on custom interactive elements. - Font weights: font-body, font-medium, font-strong, font-heading; headings add tracking-heading. - Radius: rounded-xs|sm|md|lg|xl|2xl. Shadows: shadow-xs|sm|md|lg. All change per weight. - Weight: data-weight="thin|medium|bold" on or any subtree. Variants thin: and bold:. Dark mode: class "dark". - Icons: ; Buttons take leadingIcon / trailingIcon names. - Mobile-first; container-k for page gutters; text-display-md|lg|xl for hero headings. - Prefer existing components: utils, tokens, accordion, alert-dialog, alert, aspect-ratio, avatar, badge, breadcrumb, button-group, button, calendar, card, carousel, chart, checkbox, collapsible, combobox, command, commerce, context-menu, date-picker, dialog, dropdown-menu, empty-state, field, hover-card, icon, input-otp, input, item, kbd, label, layout, logo, menubar, navigation-menu, pagination, popover, progress, radio-group, resizable, scroll-area, select, separator, skeleton, slider, spinner, stat, steps, switch, table, tabs, toast, toggle, tooltip, typography, block-checkout, block-data-table, block-settings-form, block-sign-in, section-app-shell, section-content, section-hero, section-marketing, section-navbar, template-blog, template-corporate, template-dashboard, template-ecommerce. --- # Introduction **Kontenedor** is a professional design system for designers, developers and AI agents. It gives you one source of truth — design tokens — expressed as **CSS variables**, a **Tailwind CSS v4 theme**, **React components** you own, a **Figma library** with Variables, and a **machine-readable registry** for AI. ## Principles 1. **Tokens first.** Components never hard-code colors, radii or shadows; they use semantic tokens such as `bg-primary` or `rounded-md`. 2. **Own the code.** Components are copied into your project with the CLI. Change anything — no black box. 3. **Accessible by default.** Built on Radix primitives: keyboard, focus and ARIA handled. WCAG AA contrast in light and dark. 4. **Three weights.** The same component renders as **Thin**, **Medium** or **Bold** by switching one attribute. 5. **Responsive.** Mobile-first, fluid type, touch-friendly sizes. 6. **AI-ready.** An MCP server, `llms.txt` and `AGENTS.md` teach AI tools to build with Kontenedor. ## What's inside | Layer | Package | Free preview | Pro ($49 lifetime) | | --- | --- | --- | --- | | Tokens | `@kontenedor/tokens` | ✓ | ✓ | | Core components | Button, Badge, Card, Input, Field, Icon… | ✓ | ✓ | | Full library | Forms, overlays, navigation, data, charts, commerce | — | ✓ | | Figma library | Variables + components | Preview | ✓ | | Patterns | Dashboard, CRM, e-commerce, email | Storybook | ✓ (source) | | CLI & MCP | `kontenedor`, `@kontenedor/mcp` | Free items | All items | ## Built for Websites, landing pages, dashboards, internal systems, CRM, ERP, e-commerce, email campaigns and presentations — see [Project types](/docs/project-types). Continue with [Installation](/docs/installation). --- # Installation Kontenedor works with any React framework (Next.js, Vite, Remix, Astro) and **Tailwind CSS v4**. ## 1. Initialize ```bash npx kontenedor init ``` This creates `kontenedor.json`, copies the tokens (`styles/kontenedor.css`, `styles/tailwind.css`) and the `cn()` utility, and installs `clsx` and `tailwind-merge`. ## 2. Import the styles In your main CSS file: ```css @import "tailwindcss"; @import "./components/kontenedor/styles/tailwind.css"; @source "./components/kontenedor"; ``` ## 3. Load Google Fonts and Material Symbols ```html ``` In Next.js put these in `app/layout.tsx` inside ``. ## 4. Add components ```bash npx kontenedor add button card input npx kontenedor add --all # everything your license allows ``` Dependencies (other components, npm packages) are resolved automatically. ## 5. Pro license After purchase, Polar emails your license key. Add it once: ```bash npx kontenedor login kt_your_license_key # or set the environment variable export KONTENEDOR_LICENSE=kt_your_license_key ``` ## 6. Use it ```tsx import { Button } from "@/components/kontenedor/ui/button"; export default function Page() { return ; } ``` Set the weight on `` (or `thin` / `bold`) and the theme with the `dark` class. ## Alternative: clone the repository Buyers get access to the private GitHub repository. You can use the monorepo directly (`pnpm install && pnpm storybook`) or consume `packages/ui` as a workspace package. --- # Components Explore every component, variant and state live in **[Storybook](/storybook)** — switch weight and theme from the toolbar. | Category | Components | | --- | --- | | Foundation | Icon, Logo, Typography (H1–H4, Lead, Prose…), Layout, Aspect Ratio, Scroll Area, Resizable | | Actions | Button, Button Group, Toggle, Toggle Group, Badge, Kbd | | Forms | Input, Textarea, Label, Field, Checkbox, Radio Group, Switch, Select, Combobox, Slider, Input OTP, Calendar, Date Picker, Date Range Picker | | Navigation | Navbar, Navigation Menu, Sidebar, App Shell, Menubar, Tabs, Accordion, Collapsible, Breadcrumb, Pagination, Steps, Dropdown Menu, Context Menu, Command | | Overlays | Dialog, Alert Dialog, Sheet / Drawer, Popover, Hover Card, Tooltip, Toast | | Data display | Card, Item, Table, Avatar, Stat, Charts, Progress, Skeleton, Empty State, Alert, Carousel | | Commerce | Price, Rating, ProductCard | | Sections | Hero (centered, split, image), Page header, Logo cloud, Feature grid, Feature split, Stats, Testimonials, Pricing, CTA, FAQ, Newsletter, Team, Post card/grid, Article header, Contact, Footer | | Blocks | Data table, Sign-in, Settings form, Checkout | | Templates | Dashboard / CRM, E-commerce, Blog / Magazine, Corporate / B2B — see [/templates](/templates) | ## Conventions - Every component accepts `className` and merges it with `cn()`. - Variants are defined with `cva` and exported (`buttonVariants`) so you can reuse styles. - `asChild` renders the styles on your own element (e.g. a Next.js `Link`). - Icons are passed by **Material Symbols name**: `leadingIcon="add"`. - Parts expose `data-slot` attributes for targeted styling. ## Example ```tsx ``` ## Icons Kontenedor uses **Google Material Symbols (Rounded)** — 3,000+ icons. Browse them at [fonts.google.com/icons](https://fonts.google.com/icons) and use the name: ```tsx ``` --- # Weights A **weight** is a coordinated set of tokens that changes the visual intensity of every component at once. Components stay identical in API and structure. | Token | Thin | Medium | Bold | | --- | --- | --- | --- | | Border width | 1px | 1px | 2px (ink) | | Radius md | 4px | 8px | 12px | | Shadows | none | soft | hard offset | | Body / heading weight | 300 / 300 | 400 / 600 | 500 / 800 | | Icon stroke (Material Symbols `wght`) | 200 | 400 | 600, filled | | Control height md | 36px | 40px | 44px | | Focus ring | 1px | 2px | 3px | ## Switching ```html
``` ```tsx import { KontenedorScope } from "@/components/kontenedor/ui/layout"; … ``` ## Weight-aware utilities Use these in your own components so they respond to the weight: - `border-k`, `border-k-t`, `border-k-b` — border width follows the weight. - `focus-ring` — accessible focus outline. - `press` — tactile press offset (Bold only). - `font-body`, `font-medium`, `font-strong`, `font-heading` and `tracking-heading`. - Variants `thin:` and `bold:` — e.g. `bold:shadow-md thin:border-border`. ## When to use each - **Thin** — editorial, luxury, portfolios, marketing sites, email. - **Medium** — SaaS, dashboards, CRM, ERP, e-commerce. The default. - **Bold** — campaigns, launches, keynotes, gaming, education, expressive brands. You can mix them: a Medium product with a Bold marketing hero. --- # Design tokens Tokens are defined once in `packages/tokens/src/tokens.mjs` and generated into: - `kontenedor.css` — framework-agnostic CSS variables (`--k-*`). - `tailwind.css` — the Tailwind v4 `@theme`, utilities and variants. - `tokens.json` — W3C Design Tokens (DTCG) format. - `figma-variables.json` — collections and modes for Figma. ## Layers 1. **Primitives**: raw palettes (`ink`, `cobalt`, `green`, `amber`, `red`, `cyan`) in OKLCH. 2. **Semantic roles**: what components use (`background`, `foreground`, `surface`, `muted`, `border`, `primary`, `success`…). 3. **Weight**: radius, borders, shadows, font weights, icon axes, control heights. ## Color roles | Role | Tailwind | Use | | --- | --- | --- | | background / foreground | `bg-background text-foreground` | Page | | surface | `bg-surface` | Cards, panels | | muted / muted-foreground | `bg-muted text-muted-foreground` | Secondary text, fills | | subtle | `bg-subtle` | Hover rows, sections | | border / border-strong / input | `border-border` | Dividers, outlines | | primary (+ -foreground, -subtle) | `bg-primary` | Main actions, brand | | success · warning · danger · info | `bg-success-subtle` | Status | | inverse | `bg-inverse` | Tooltips, high contrast | | chart-1…5 | `var(--k-chart-1)` | Data viz | Every color has a dark-mode value. Raw palettes are available as `bg-k-cobalt-500`, but prefer semantic roles. ## Typography - **Geist** (sans) and **Geist Mono** from Google Fonts. - Scale `text-2xs` → `text-7xl`, plus fluid `text-display-md|lg|xl` for hero headings. ## Breakpoints | Name | Min width | Device | | --- | --- | --- | | `sm` | 640px | Large phones | | `md` | 768px | Tablet | | `lg` | 1024px | Desktop | | `xl` | 1280px | Wide desktop | | `2xl` | 1536px | Ultra-wide | ## Motion `--k-duration-fast` 120ms · `--k-duration-base` 180ms · `--k-duration-slow` 280ms · `--k-ease-out`. `prefers-reduced-motion` is respected globally. --- # Theming & branding ## Dark mode Add the `dark` class (or `data-theme="dark"`) to `` or any element. All semantic tokens switch. ## Your brand color Override the semantic variables after importing Kontenedor: ```css :root { --k-primary: oklch(0.62 0.19 150); /* green brand */ --k-primary-foreground: oklch(1 0 0); --k-primary-subtle: oklch(0.96 0.04 150); --k-primary-subtle-foreground: oklch(0.45 0.13 150); --k-ring: oklch(0.62 0.19 150); } .dark { --k-primary: oklch(0.7 0.18 150); } ``` ## Your fonts ```css :root { --k-font-sans: "Inter", sans-serif; --k-font-display: "Space Grotesk", sans-serif; } ``` Any Google Font works. Variable fonts get the most out of the weights. ## Multiple brands Scope variables to a class (`.brand-acme { --k-primary: … }`) to run several brands — for agencies, white-label products or multi-tenant SaaS — on the same components. --- # Responsive design Kontenedor is **mobile-first**: base styles target phones and grow with `md:` (tablet) and `lg:` (desktop). ## Rules - **Gutters**: 16px mobile → 32px tablet → 40px desktop (`container-k` or ``). - **Touch targets**: controls are ≥ 36px (Thin) / 40px (Medium) / 44px (Bold). - **Type**: hero headings use fluid `text-display-*` that scale with the viewport. - **Tables** scroll horizontally on small screens; hide low-priority columns with `hidden md:table-cell`. - **Navigation**: collapse to a `Sheet` below `lg`. - **Dialogs** become full-width with margins on mobile; use `SheetContent side="bottom"` for mobile actions. - **Grids**: `grid sm:grid-cols-2 lg:grid-cols-4` for stat rows and product grids. ## Test sizes Storybook includes Mobile (375), Tablet (768) and Desktop (1440) viewports. Figma frames use the same sizes. --- # Figma library The Figma library mirrors the code 1:1 — same token names, same component names, same variants. ## Variables | Collection | Modes | Contains | | --- | --- | --- | | Primitives | Value | ink, cobalt, green, amber, red, cyan, lime, violet | | Color | Light, Dark | All semantic roles (background, primary, border…) | | Weight | Thin, Medium, Bold | radius, border width, font weights, icon weight, control heights | Switch a frame's **Color** mode to Dark and **Weight** mode to Bold and every component updates — exactly like `data-weight` in code. ## Components Built with auto-layout and component properties (variant, size, state, icon, label). Names match React props: `Button / variant=primary, size=md`. ## Fonts & icons Install **Geist**, **Geist Mono** and **Material Symbols Rounded** from Google Fonts. Icons are typed as ligatures (e.g. `home`) so they match code. ## Access Buyers receive the library link by email (Polar benefit). Duplicate it into your team, then **Publish** it as a team library. ## Designer → developer handoff Component names, variants and token names are identical in Figma and code. With **Figma Dev Mode** + **Code Connect**, inspecting a component shows the Kontenedor React snippet. ## Free preview A preview of the Figma library (cover, foundations, core components and the four templates) is available on the Figma Community — see the **Figma preview** button on the [home page](/#pricing). The full library with every component is delivered to buyers. --- # AI & MCP Kontenedor is designed so AI coding agents produce on-brand, consistent UI. ## MCP server Add the server to Claude Code, Cursor, VS Code, Windsurf or any MCP client: ```json { "mcpServers": { "kontenedor": { "command": "npx", "args": ["-y", "@kontenedor/mcp"], "env": { "KONTENEDOR_LICENSE": "kt_your_license_key" } } } } ``` Claude Code one-liner: ```bash claude mcp add kontenedor -e KONTENEDOR_LICENSE=kt_… -- npx -y @kontenedor/mcp ``` ### Tools | Tool | What it does | | --- | --- | | `list_components` | Catalog with category, description and access level | | `get_component` | Full source + dependencies for a component | | `get_tokens` | Tokens as CSS, Tailwind or JSON | | `get_guidelines` | Usage rules: weights, layout, a11y, project types | | `search_icons` | Suggests Material Symbols names for a concept | ## llms.txt - [`/llms.txt`](/llms.txt) — concise index for LLMs. - [`/llms-full.txt`](/llms-full.txt) — complete docs + component API in one file. Paste the URL into ChatGPT, Claude, v0, Lovable or Bolt: *"Use the Kontenedor design system from https://kontenedor.com/llms-full.txt"*. ## AGENTS.md Copy `AGENTS.md` from the repository into your project root. It tells agents to: - use semantic tokens (`bg-primary`) — never raw hex; - use Kontenedor components before writing new ones; - use `Icon` with Material Symbols names; - respect `data-weight` and dark mode; - design mobile-first. ## Prompts that work well - "Build a CRM customers page with Kontenedor: Stat row, filters, Table with Badge statuses, Pagination. Medium weight." - "Create a Bold-weight launch landing page with a hero, 3 feature cards and pricing." - "Make a Thin-weight checkout with Steps, Field inputs and a summary Card." --- # Project types Kontenedor ships recipes for the products teams build most. ## Marketing websites & landing pages `Section`, `SectionHeader`, `Container`, Button `size="lg"`, `Card`, `Accordion` (FAQ). Consider **Thin** for editorial or **Bold** for campaigns. Use `text-display-*` for heroes. ## Dashboards & analytics App shell (sidebar + topbar), `Stat` row, `BarChart` / `DonutChart` / `Sparkline`, `Tabs` for ranges, `Table`. **Medium** weight. See *Patterns → Dashboard* in Storybook. ## Systems, CRM & ERP Dense `Table` with `Badge` statuses, `DropdownMenu` row actions, `Dialog` / `Sheet` forms with `Field`, `Pagination`, `Breadcrumb`, `EmptyState`, `Toast` feedback. **Medium** weight. Reduce paddings for density. ## E-commerce `ProductCard`, `Price`, `Rating`, `Steps` for checkout, `Select` for variants, `Sheet` for cart and filters. Any weight — Bold works great for streetwear and youth brands; Thin for luxury. ## Email campaigns Email clients don't support CSS variables or modern CSS. Use the token values from `tokens.json` (hex in `figma-variables.json`) with React Email or MJML: 600px max width, Geist with Arial fallback, table layouts, bulletproof buttons using `primary`. **Thin** and **Medium** read best in inboxes. ## Presentations & slides Pitch decks, reports, workshops and keynotes. Design slides at **1920×1080 (16:9)** in Figma or build them in code as `aspect-video` frames. Use `text-display-*` for titles, `Stat` and charts for data slides, and `Card` grids for comparisons. Keep one idea per slide. **Bold** for keynotes and launches, **Thin** for editorial reports, **Medium** for business reviews. See *Patterns → Presentation* in Storybook. --- # License **Free preview** — the tokens and the free components may be used in any personal or commercial project. **Kontenedor Pro (lifetime, $49)** — one person (or one seat) may use the full library, Figma files, patterns, CLI and MCP in **unlimited personal and commercial projects**, including client work, and receive all future updates. You may **not**: - resell, redistribute or sublicense Kontenedor (code or Figma) as a design system, UI kit, template or theme; - share your license key or repository access; - create a competing product with Kontenedor's source. Purchases are processed by Polar (merchant of record). Questions: reply to your Polar receipt email.