# Be Partner DS

![OG](public/og.png)

A CSS-first, token-driven, framework-agnostic design system by [BePartnerLabs](https://bepartnerlabs.com). No build step required for consumers — drop in a stylesheet and go.

**[Documentation →](https://ds.bepartnerlabs.com)**

[![npm](https://img.shields.io/npm/v/@be-partner-labs/ds?color=5fcb9f&label=npm)](https://www.npmjs.com/package/@be-partner-labs/ds)
[![license](https://img.shields.io/github/license/BePartnerLabs/bpl-ds?color=5fcb9f)](LICENSE)
[![WCAG AA](https://img.shields.io/badge/WCAG-AA-5fcb9f)](https://ds.bepartnerlabs.com)

---

## Installation

### CDN (no build step)

```html
<!-- Full bundle, minified -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@be-partner-labs/ds/dist/bpl-ds.min.css" />

<!-- Core only (tokens + reset + grid) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@be-partner-labs/ds/dist/core/index.min.css" />

<!-- Core + individual component -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@be-partner-labs/ds/dist/core/index.min.css" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@be-partner-labs/ds/dist/components/button.min.css" />
```

### npm

```bash
npm install @be-partner-labs/ds
# or
pnpm add @be-partner-labs/ds
```

```css
/* Full bundle */
@import "@be-partner-labs/ds";

/* Core only */
@import "@be-partner-labs/ds/core";

/* Individual components */
@import "@be-partner-labs/ds/components/button";
@import "@be-partner-labs/ds/components/card";
@import "@be-partner-labs/ds/components/modal";
```

### JS-enhanced components

Some components require a small Custom Element for keyboard navigation:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@be-partner-labs/ds/dist/js/bp-dropdown.esm.min.js"></script>
<script type="module" src="https://cdn.jsdelivr.net/npm/@be-partner-labs/ds/dist/js/bp-table.esm.min.js"></script>
<script type="module" src="https://cdn.jsdelivr.net/npm/@be-partner-labs/ds/dist/js/bp-toast.esm.min.js"></script>
```

---

## Usage

```html
<button class="bp-btn bp-btn--primary">Get started</button>
```

Customise via CSS custom properties — no source modifications needed:

```css
.my-section {
  --btn-bg: var(--bp-color-success);
  --btn-radius: var(--bp-radius-full);
}
```

---

## Components

| Component | Description | JS required |
|---|---|---|
| Accordion | Native `<details>`/`<summary>` with animated open/close | No |
| Alert | Info, success, warning, error banners with dismissible state | No |
| Avatar | Image with CSS-only initials fallback, group stacking | No |
| Badge | Semantic status labels | No |
| Breadcrumb | `<nav>` + `aria-current="page"` | No |
| Button | Primary, secondary, ghost, danger, icon, sizes | No |
| Card | Composable content container | No |
| Carousel | CSS scroll-snap with roving tabindex | No |
| Checkbox | Custom checkbox with indeterminate state and group layout | No |
| Datepicker | Native `<input type="date">` styled with `accent-color` | No |
| Dropdown | Keyboard-navigable menu | `bp-dropdown.js` |
| Footer | Site footer with responsive column grid | No |
| Header | Sticky header with scroll state | No |
| Hero | Page hero with `@starting-style` entrance animation | No |
| Input | Text, textarea, select — label + validation states | No |
| Modal | Native `<dialog>` with focus management | No |
| Nav | Primary navigation | No |
| Pagination | `<nav>` + `<ol>` with `aria-current` / `aria-disabled` | No |
| Popover | Native Popover API — no JS, top layer | No |
| Radio | Radio button group with horizontal layout modifier | No |
| Skeleton / Spinner | Loading placeholders with shimmer animation | No |
| Table | Sortable columns via `aria-sort` | `bp-table.js` |
| Tabs | ARIA-driven tab panels | No |
| Theme | CSS color scheme switcher | No |
| Toast | Stacked notifications with auto-dismiss | `bp-toast.js` |
| Toggle | Switch input with `role="switch"`, size variants | No |
| Tooltip | CSS-only with optional CSS Anchor Positioning | No |

---

## Design tokens

All tokens are CSS custom properties on `:root`:

```css
--bp-primary            /* brand accent */
--bp-color-text         /* body text */
--bp-color-bg           /* page background */
--bp-color-border       /* default border */
--bp-color-success      /* success green */
--bp-color-error        /* error red */
--bp-color-warning      /* warning yellow */
--bp-color-info         /* info blue */
--bp-space-{1–10}       /* spacing scale */
--bp-radius-{sm|md|lg|xl|full}
--bp-shadow-{sm|md|lg}
--bp-font-size-{sm|md|lg|xl}
```

Full token reference at [ds.bepartnerlabs.com/tokens/tokens](https://ds.bepartnerlabs.com/tokens/tokens/).

---

## Principles

- **CSS reads the DOM — JS writes to the DOM.** State lives in ARIA attributes and native CSS pseudo-classes. No style classes toggled from JS.
- **Native HTML first.** `<dialog>` over `<div role="dialog">`, `<details>` over custom accordions.
- **Progressive enhancement.** Every component works without JavaScript. JS adds keyboard navigation via Custom Elements.
- **WCAG AA.** All components pass axe-core audits. Accessibility is built in, not bolted on.
- **No build step for consumers.** One `<link>` tag and you're done.

---

## Agentic usage

BPL DS is built as a **definition-first** design system — components are contracts, not implementations. Agents implementing UI read the contract and generate conforming HTML + CSS without inference or translation.

After installing, agent instructions are available at:

```
node_modules/@be-partner-labs/ds/AGENTS.md   ← local, works offline
https://ds.bepartnerlabs.com/AGENTS.md       ← online, always current
```

Add to your `CLAUDE.md`, `.cursorrules`, or agent system prompt:

```markdown
## BPL DS
Agent instructions: node_modules/@be-partner-labs/ds/AGENTS.md
Implementation skill: https://ds.bepartnerlabs.com/skills/bpl-ds-implement/SKILL.md
Verification skill: https://ds.bepartnerlabs.com/skills/bpl-ds-verify/SKILL.md
```

---

## Development

```bash
pnpm install        # install dependencies
pnpm dev            # docs site at localhost:4321
pnpm build:dist     # build consumer CSS/JS to ./dist/
pnpm build          # build docs site to ./dist/
pnpm format         # Biome + Prettier
pnpm lint           # Biome lint
```

### Release

```bash
git tag v1.2.0
git push origin v1.2.0
```

GitHub Actions will publish to npm and deploy the docs to Cloudflare Pages automatically.

---

## License

MIT © [BePartnerLabs](https://bepartnerlabs.com)