@bpjs/design-system 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,709 @@
-# Temporary Holding Version
+# @bpjs/design-system
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-agnostic design system for BPJS Kesehatan. It ships design tokens, CSS components and a small plain-JavaScript module. Everything is generated from the Figma file "BPJS Design System 1.1 (1110)", so the code follows the design file.
+
+Works with React, Vue, Angular, Laravel Blade or plain HTML. Components are plain CSS classes; behavior is plain ES modules with no dependencies.
+
+**License:** UNLICENSED for now. No use rights are granted until a license is added. See [License](#license).
+
+- **Components built:** Button, Modal, Icons, Texts, Text Field, Form Item, Textarea, Checkbox, Radio, Radio Card, Switch, Pills, Avatar, Badge, Swiper, Stepper, Tooltip, Dropdown, Select, Segmented, Pagination, Table, Empty State and File Upload.
+- **Not built yet:** Date Picker and Time Picker. Their Figma pages are still empty, so they wait for the designer.
+- **Foundation:** tokens (colors, spacing, radius, typography, effects, layout grids) and the bundled Plus Jakarta Sans font are in place.
+
+## Contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Fonts](#fonts)
+- [Theming](#theming)
+- [Tokens](#tokens)
+- [Components](#components)
+- [Icons](#icons)
+- [JavaScript API](#javascript-api)
+- [Browser support](#browser-support)
+- [Accessibility](#accessibility)
+- [Known gaps](#known-gaps)
+- [License](#license)
+
+## Install
+
+```bash
+npm install @bpjs/design-system
+```
+
+## Quick start
+
+With a bundler (Vite, webpack, esbuild):
+
+```js
+import "@bpjs/design-system/css";
+import { init } from "@bpjs/design-system";
+
+init();
+```
+
+Plain HTML from a CDN:
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/@bpjs/design-system/dist/bpjs.css" />
+<script src="https://unpkg.com/@bpjs/design-system/dist/bpjs.iife.js" defer></script>
+```
+
+The IIFE build calls `init()` on load and exposes `window.BPJS`.
+
+## Fonts
+
+Plus Jakarta Sans is bundled with `bpjs.css`: latin and latin-ext subsets, variable weight 200 to 800, `font-display: swap`. The font is licensed under the SIL Open Font License 1.1, and the license ships as `dist/fonts/OFL.txt`.
+
+If your app already loads Plus Jakarta Sans, use the build without the font to avoid downloading it twice:
+
+```js
+import "@bpjs/design-system/css/nofont";
+```
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/@bpjs/design-system/dist/bpjs.nofont.css" />
+```
+
+Components set the font through the text tokens, so their text uses Plus Jakarta Sans. Text outside a component (your own headings and paragraphs) uses your page's font. To match the design, set `font-family: var(--bpjs-font-family)` on your page root, or add the `bpjs-theme` class to it.
+
+## Theming
+
+Light is the default. Set `data-theme="dark"` on any element to switch its subtree:
+
+```html
+<div data-theme="dark">...</div>
+```
+
+To change a brand value for part of a page, override the semantic token on a parent. Components read semantic tokens, so the override reaches them:
+
+```css
+.my-app {
+  --bpjs-background-brand-primary: #0a7a4a;
+}
+```
+
+## Tokens
+
+Every token is a CSS custom property named after its Figma path, prefixed with `--bpjs-`:
+
+| Figma | CSS variable |
+| --- | --- |
+| `Modes/Background/background-brand-primary` | `--bpjs-background-brand-primary` |
+| `Spacing/Standard/spacing-md` | `--bpjs-spacing-md` |
+| `Radius/radius-md` | `--bpjs-radius-md` |
+| `Effects/Focus Normal` | `--bpjs-focus-normal` |
+| Text style `Text/SM/Semibold` | `--bpjs-text-sm-semibold` (a `font` shorthand) |
+| Layout grid `Dekstop` | `--bpjs-layout-grid-desktop-columns` |
+
+Text styles also have utility classes, such as `.bpjs-type-text-sm-semibold`.
+
+Two token files are available for use outside CSS:
+
+- `@bpjs/design-system/tokens/light.json`
+- `@bpjs/design-system/tokens/dark.json`
+
+They hold fully resolved values, with one token per key.
+
+Use `@bpjs/design-system/tokens.css` on its own if you only need the variables.
+
+## Components
+
+Optional `__label` spans inherit the control's color and font, so you can leave them out or add your own styling.
+
+### Button
+
+```html
+<button type="button" class="bpjs-button bpjs-button--primary bpjs-button--md">Save</button>
+```
+
+- Variants: `--primary` (default), `--secondary`, `--tertiary`, `--ghost`, `--text`, `--danger`
+- Sizes: `--sm`, `--md` (default), `--lg`, `--xl`
+- Modifiers: `--gradient` (the Figma Gradient set), `--block`, `--icon-only` (needs an `aria-label`)
+- Disabled: the `disabled` attribute on `<button>`, or `aria-disabled="true"` on a link
+- Loading: `aria-busy="true"` shows a spinner and keeps the width
+
+### Modal
+
+```html
+<button type="button" data-bpjs-modal-open="confirm-delete">Delete item</button>
+
+<dialog class="bpjs-modal bpjs-modal--sm" id="confirm-delete" aria-labelledby="confirm-title"
+        aria-describedby="confirm-desc">
+  <header class="bpjs-modal__header">
+    <div class="bpjs-modal__titles">
+      <h2 class="bpjs-modal__title" id="confirm-title">Delete item?</h2>
+      <p class="bpjs-modal__description" id="confirm-desc">This cannot be undone.</p>
+    </div>
+    <button type="button" class="bpjs-modal__close" aria-label="Close" data-bpjs-modal-close>
+      <!-- close icon svg -->
+    </button>
+  </header>
+  <div class="bpjs-modal__body">Content goes here.</div>
+  <footer class="bpjs-modal__footer bpjs-modal__footer--end">
+    <button type="button" class="bpjs-button bpjs-button--secondary" data-bpjs-modal-close="cancel">Cancel</button>
+    <button type="button" class="bpjs-button bpjs-button--danger" data-bpjs-modal-close="confirm">Delete</button>
+  </footer>
+</dialog>
+```
+
+- Sizes: `--sm` (480px, default), `--md` (600px), `--lg` (720px)
+- The native `<dialog>` handles focus trapping, the Esc key and the backdrop.
+- Click outside the box to close. Add `data-bpjs-backdrop-close="false"` to turn this off.
+- Closing with `data-bpjs-modal-close="value"` sets `dialog.returnValue` to `value`.
+- Focus returns to the button that opened the modal.
+
+### Texts
+
+Four blocks match Figma's Texts page. Use whatever heading level suits the page, since the classes work on any element:
+
+```html
+<h2 class="bpjs-heading bpjs-heading--lg bpjs-heading--bold">Judul halaman</h2>
+<p class="bpjs-subtitle bpjs-subtitle--lg">Subjudul</p>
+<p class="bpjs-body">Body Small, Regular, High (default)</p>
+<p class="bpjs-body bpjs-body--lg bpjs-body--level-medium">Body Large, Medium</p>
+<small class="bpjs-note bpjs-note--level-low">Catatan</small>
+```
+
+- Heading sizes: `--2xl`, `--xl`, `--lg`, `--md` (default), `--sm`, `--xs`
+- Subtitle and body sizes: `--lg`, `--sm` (default). Note has one size.
+- Weights: `--medium`, `--semibold`, `--bold`, `--extra-bold` (default is Regular)
+- Levels (subtitle, body and note): `--level-medium`, `--level-low`, `--level-very-low` (default is High). Heading has no level in Figma.
+
+### Text Field
+
+A Text Field needs a visible label, so wrap it in a Form Item (below). Every field carries the `bpjs-control-field` class, which holds the shared focus, danger and disabled styles (`form-control.css`). The state is read from the input, so there are no state classes:
+
+```html
+<div class="bpjs-text-field bpjs-control-field">
+  <span class="bpjs-text-field__addon bpjs-text-field__addon--prefix">Rp</span>
+  <input class="bpjs-text-field__control" id="iuran" type="text" inputmode="numeric" />
+  <span class="bpjs-text-field__addon bpjs-text-field__addon--suffix">/bulan</span>
+</div>
+```
+
+- Focus: the wrapper shows the focus ring when the input has focus
+- Danger: `aria-invalid="true"` on the input
+- Disabled: `disabled` on the input
+- Icons: `<svg class="bpjs-icon bpjs-text-field__icon">` (20px, inherits text color)
+
+### Textarea
+
+Figma: 100px tall including the border, with the native resize handle. Wrap it in a Form Item.
+
+```html
+<div class="bpjs-textarea bpjs-control-field">
+  <textarea class="bpjs-textarea__control" id="catatan" rows="4"></textarea>
+</div>
+```
+
+The same states as Text Field apply: `aria-invalid="true"` for danger and `disabled` for disabled.
+
+### Form Item
+
+Form Item groups a label, a control and an optional caption. Label, control and caption are 6px apart:
+
+```html
+<div class="bpjs-form-item">
+  <label class="bpjs-form-item__label" for="nik">NIK</label>
+  <div class="bpjs-text-field bpjs-control-field">
+    <input class="bpjs-text-field__control" id="nik" type="text" aria-describedby="nik-caption" />
+  </div>
+  <p class="bpjs-form-item__caption" id="nik-caption">
+    <svg class="bpjs-icon bpjs-icon--sm" aria-hidden="true"><use href="icons.svg#info"></use></svg>
+    <span>Masukkan 16 digit NIK sesuai KTP</span>
+  </p>
+</div>
+```
+
+- Danger: set `aria-invalid="true"` on the control. The caption turns red and uses the alert icon.
+- Disabled: set `disabled` on the control. The label and caption turn gray.
+
+### Checkbox
+
+Figma: 16px by default (Small) and 20px for Large (`bpjs-checkbox--lg`). Checked, indeterminate and disabled states come from the input.
+
+```html
+<label class="bpjs-checkbox">
+  <input class="bpjs-checkbox__control" type="checkbox" name="setuju" />
+  <span class="bpjs-checkbox__box" aria-hidden="true">
+    <svg class="bpjs-icon bpjs-checkbox__mark bpjs-checkbox__mark--check"><use href="icons.svg#check"></use></svg>
+    <svg class="bpjs-icon bpjs-checkbox__mark bpjs-checkbox__mark--minus"><use href="icons.svg#minus"></use></svg>
+  </span>
+  <span class="bpjs-checkbox__label">Saya setuju dengan syarat dan ketentuan</span>
+</label>
+```
+
+The mixed ("indeterminate") state is set from JavaScript, since HTML has no attribute for it. It clears when the user toggles the box:
+
+```js
+import { setIndeterminate } from "@bpjs/design-system";
+
+setIndeterminate(selectAll, true); // some, but not all, items are selected
+```
+
+### Radio
+
+Figma: 16px (Small) or 20px (`bpjs-radio--lg`). Options that share a `name` form a group. Arrow keys move between enabled options and skip disabled ones, which `init()` wires up.
+
+```html
+<fieldset>
+  <legend>Pilih paket</legend>
+  <label class="bpjs-radio">
+    <input class="bpjs-radio__control" type="radio" name="paket" value="a" checked />
+    <span class="bpjs-radio__dot" aria-hidden="true"></span>
+    <span class="bpjs-radio__label">Paket A</span>
+  </label>
+  <label class="bpjs-radio">
+    <input class="bpjs-radio__control" type="radio" name="paket" value="b" />
+    <span class="bpjs-radio__dot" aria-hidden="true"></span>
+    <span class="bpjs-radio__label">Paket B</span>
+  </label>
+</fieldset>
+```
+
+### Radio Card
+
+A bordered option card around a radio: an icon, a value and a description, with the radio on the right. The card is 10px rounded with 16px padding. It is checked and unchecked the same way as Radio, and it groups with arrow keys in the same way.
+
+```html
+<label class="bpjs-radio-card">
+  <input class="bpjs-radio-card__control bpjs-radio__control" type="radio" name="paket" value="a" checked />
+  <span class="bpjs-radio__dot" aria-hidden="true"></span>
+  <span class="bpjs-radio-card__icon" aria-hidden="true">
+    <svg class="bpjs-icon"><use href="icons.svg#info"></use></svg>
+  </span>
+  <span class="bpjs-radio-card__content">
+    <span class="bpjs-radio-card__value">Paket A</span>
+    <span class="bpjs-radio-card__description">Rawat jalan dan rawat inap kelas III</span>
+  </span>
+</label>
+```
+
+### Switch
+
+Figma: 36×20 (Small) or 44×24 (`bpjs-switch-field--lg`). A switch needs an accessible name, so it always has a label. If the design shows no text, hide the label visually with `bpjs-sr-only`; it is still read by screen readers.
+
+```html
+<label class="bpjs-switch-field">
+  <input class="bpjs-switch" type="checkbox" role="switch" name="notif" />
+  <span class="bpjs-switch__track" aria-hidden="true"><span class="bpjs-switch__thumb"></span></span>
+  <span class="bpjs-switch__label">Notifikasi</span>
+</label>
+```
+
+Enter toggles a switch as well as Space.
+
+### Pills
+
+A compact toggle chip, 32px tall. It can have a leading icon and a count badge.
+
+```html
+<button type="button" class="bpjs-pill bpjs-pill--active" aria-pressed="true">
+  <svg class="bpjs-icon bpjs-pill__icon" aria-hidden="true"><use href="icons.svg#check"></use></svg>
+  <span class="bpjs-pill__label">Label</span>
+  <span class="bpjs-pill__badge"><span class="bpjs-pill__dot" aria-hidden="true"></span>2</span>
+</button>
+```
+
+For single choice, use a Radio Pill. Its radio is part of the pill, and arrow keys move between options that share a `name`:
+
+```html
+<label class="bpjs-pill bpjs-pill--radio">
+  <input class="bpjs-radio__control" type="radio" name="filter" value="a" checked />
+  <span class="bpjs-radio__dot" aria-hidden="true"></span>
+  <span class="bpjs-pill__label">Label</span>
+</label>
+```
+
+Active and checked pills use the brand border and text. Disabled pills use `disabled` on the button or input.
+
+The leading icon is not final. See [Known gaps](#known-gaps).
+
+### Avatar
+
+Figma has six sizes, from 24px to 64px. An avatar shows a photo, an icon or initials, and can carry an online dot.
+
+```html
+<span class="bpjs-avatar bpjs-avatar--md">
+  <img class="bpjs-avatar__image" src="foto.jpg" alt="Budi Santoso" />
+</span>
+<span class="bpjs-avatar bpjs-avatar--md" role="img" aria-label="Ani Wijaya">
+  <span class="bpjs-avatar__text" aria-hidden="true">AW</span>
+  <span class="bpjs-avatar__status" aria-hidden="true"></span>
+</span>
+```
+
+- Sizes: `--xs` (24px), `--sm` (32px), `--md` (40px, default), `--lg` (48px), `--xl` (56px), `--2xl` (64px)
+- Content: a photo (`bpjs-avatar__image`), an icon (`<svg class="bpjs-icon bpjs-avatar__icon">`, 60% of the size), or initials (`bpjs-avatar__text`)
+- Status: add `bpjs-avatar__status` for the green Active dot. Figma's Status set has four types, and each one is a modifier:
+  - `bpjs-avatar__status` (no modifier): Active, green
+  - `bpjs-avatar__status--inactive`: gray dot
+  - `bpjs-avatar__status--badge`: red circle with a count inside, e.g. `<span class="bpjs-avatar__status bpjs-avatar__status--badge">8</span>`
+  - `bpjs-avatar__status--icon`: white circle with an icon inside, e.g. `<span class="bpjs-avatar__status bpjs-avatar__status--icon"><svg class="bpjs-icon">…</svg></span>`
+- The status scales with the avatar size. Hide it from assistive tech with `aria-hidden="true"` unless the status is announced elsewhere.
+- A photo needs `alt`. An icon or initials avatar needs `role="img"` and an `aria-label`.
+
+### Badge
+
+Figma has five types, two weights and three sizes.
+
+```html
+<span class="bpjs-badge bpjs-badge--success bpjs-badge--hard">
+  <span class="bpjs-badge__dot" aria-hidden="true"></span>
+  <span class="bpjs-badge__label">Aktif</span>
+</span>
+```
+
+- Types: `--neutral` (default), `--info`, `--success`, `--warning`, `--danger`
+- Weights: Soft is the default. Add `--hard` for a tinted fill with a colored border. A hard badge also colors its label by type.
+- Sizes: 22px by default, `--md` (24px) and `--lg` (28px)
+- Icons: `<svg class="bpjs-icon bpjs-badge__icon">` before or after the label
+- Icon only: add `--icon-only`, put one icon inside, and set `role="img"` with an `aria-label` on the badge.
+
+### Swiper
+
+Figma's Swiper is the indicator only: dots or a progress bar that show the position in a carousel. The carousel itself is not part of this library.
+
+```html
+<div class="bpjs-swiper-dots" aria-hidden="true">
+  <span class="bpjs-swiper-dot bpjs-swiper-dot--active"></span>
+  <span class="bpjs-swiper-dot"></span>
+  <span class="bpjs-swiper-dot"></span>
+</div>
+
+<div class="bpjs-swiper-progress" style="--bpjs-swiper-progress: 33%" role="progressbar"
+     aria-valuenow="1" aria-valuemin="1" aria-valuemax="3" aria-label="Langkah 1 dari 3">
+  <span class="bpjs-swiper-progress__bar"></span>
+</div>
+```
+
+- Dots are 8px, 4px apart. The active dot uses the brand color.
+- The progress bar is 72 by 6px. Set `--bpjs-swiper-progress` to a percentage.
+- Hide the dots from assistive tech when the carousel already announces its position.
+
+### Stepper
+
+Figma has a vertical stepper with titles and notes, and a timeline with markers only. Each step is idle, active or done.
+
+```html
+<ol class="bpjs-stepper bpjs-stepper--vertical">
+  <li class="bpjs-step bpjs-step--done">
+    <span class="bpjs-step__marker">
+      <svg class="bpjs-icon bpjs-step__icon" aria-hidden="true"><use href="icons.svg#check"></use></svg>
+    </span>
+    <span class="bpjs-step__content">
+      <span class="bpjs-step__title">Isi data peserta</span>
+      <span class="bpjs-step__note">Nama, NIK, dan tanggal lahir</span>
+    </span>
+  </li>
+  <li class="bpjs-step bpjs-step--active" aria-current="step">
+    <span class="bpjs-step__marker"><span class="bpjs-step__number" aria-hidden="true">2</span></span>
+    <span class="bpjs-step__content">
+      <span class="bpjs-step__title">Verifikasi</span>
+    </span>
+  </li>
+</ol>
+```
+
+- Orientation: `bpjs-stepper--vertical` (titles and notes) or `bpjs-stepper--timeline` (markers and lines only, no titles or notes)
+- States: `bpjs-step--idle`, `bpjs-step--active` (add `aria-current="step"`) and `bpjs-step--done` (filled, with a check icon)
+- Use an ordered list, so screen readers announce the step count.
+
+### Tooltip
+
+A dark box with a title, an optional description and a pointer. It shows on hover or keyboard focus of its trigger.
+
+```html
+<span class="bpjs-tooltip-wrap">
+  <button type="button" class="bpjs-button bpjs-button--secondary bpjs-button--sm" aria-describedby="tip-simpan">Simpan</button>
+  <span role="tooltip" id="tip-simpan" class="bpjs-tooltip bpjs-tooltip--top">
+    <span class="bpjs-tooltip__title">Simpan perubahan</span>
+    <span class="bpjs-tooltip__description">Data akan tersimpan ke server</span>
+  </span>
+</span>
+```
+
+- Placement: `--top`, `--bottom`, `--left` or `--right`. For top and bottom, add `--start` or `--end` to align with an edge.
+- Add `--open` to keep it visible, for static pages.
+- Put essential information in the page, not only in a tooltip. The tooltip is shown with CSS and has no Esc key handling.
+
+### Dropdown
+
+A menu panel with an optional header, items and dividers. Your code shows and positions it.
+
+```html
+<div class="bpjs-dropdown">
+  <div class="bpjs-dropdown-header">
+    <span class="bpjs-dropdown-header__title">Akun saya</span>
+    <span class="bpjs-dropdown-header__description">user@example.com</span>
+  </div>
+  <div class="bpjs-dropdown__divider" role="separator"></div>
+  <button type="button" class="bpjs-dropdown-item">
+    <svg class="bpjs-icon bpjs-dropdown-item__leading" aria-hidden="true"><use href="icons.svg#user"></use></svg>
+    <span class="bpjs-dropdown-item__label">Profil saya</span>
+  </button>
+</div>
+```
+
+- The panel is 240px wide. Each item is 40px tall.
+- Items are buttons, so Enter and Space work. Disable an item with `disabled`.
+- For a user header, add `bpjs-dropdown-header--user` and put an avatar before the text.
+- Items have an optional leading icon. Figma's sample items have no trailing icon. For a submenu, add a trailing icon with `bpjs-dropdown-item__trailing`, such as a chevron.
+
+### Select
+
+A native `<select>` styled to match Figma. The browser handles the menu, the keyboard and screen readers. Wrap it in a Form Item.
+
+```html
+<div class="bpjs-form-item">
+  <label class="bpjs-form-item__label" for="kota">Kota</label>
+  <div class="bpjs-select bpjs-control-field">
+    <select class="bpjs-select__control" id="kota" name="kota">
+      <option value="" disabled selected hidden>Pilih kota</option>
+      <option value="jkt">Jakarta</option>
+    </select>
+    <svg class="bpjs-icon bpjs-select__icon" aria-hidden="true"><use href="icons.svg#chevron-down"></use></svg>
+  </div>
+</div>
+```
+
+- Placeholder: the first option, with `value=""`.
+- Prefix: put `<span class="bpjs-select__addon bpjs-select__addon--prefix">` before the select.
+- Danger: `aria-invalid="true"` on the select. Disabled: `disabled` on the select.
+
+### Segmented
+
+A gray track with one selected item. Use it to switch a view, such as list and grid, or to filter.
+
+```html
+<div class="bpjs-segmented" role="group" aria-label="Filter">
+  <button type="button" class="bpjs-segmented-item bpjs-segmented-item--active" aria-pressed="true">Semua</button>
+  <button type="button" class="bpjs-segmented-item" aria-pressed="false">Aktif</button>
+</div>
+```
+
+- The selected item is marked with `bpjs-segmented-item--active` and `aria-pressed="true"`. Update both when the selection changes.
+- Disable an item with `disabled`.
+- Items are 36px tall inside a 40px track.
+
+### Pagination
+
+Page numbers with previous and next buttons. Add a summary and a per-page select when needed.
+
+```html
+<nav class="bpjs-pagination" aria-label="Halaman">
+  <button type="button" class="bpjs-pagination__nav" aria-label="Sebelumnya" disabled>
+    <svg class="bpjs-icon" aria-hidden="true"><use href="icons.svg#chevron-left"></use></svg>
+  </button>
+  <ol class="bpjs-pagination__pages">
+    <li><button type="button" class="bpjs-pagination__page bpjs-pagination__page--active" aria-current="page">1</button></li>
+    <li><button type="button" class="bpjs-pagination__page">2</button></li>
+    <li><span class="bpjs-pagination__ellipsis" aria-hidden="true">…</span></li>
+    <li><button type="button" class="bpjs-pagination__page">10</button></li>
+  </ol>
+  <button type="button" class="bpjs-pagination__nav" aria-label="Berikutnya">
+    <svg class="bpjs-icon" aria-hidden="true"><use href="icons.svg#chevron-right"></use></svg>
+  </button>
+</nav>
+```
+
+- Page numbers are 32px squares. The current page has `aria-current="page"` and the brand fill.
+- Skipped pages are shown with `…`, which is not a button.
+- The previous and next buttons need an `aria-label`, since they show only an icon.
+
+### Table
+
+A card with a title, a toolbar, a table and a footer. The toolbar, footer and empty state use the parts above.
+
+```html
+<section class="bpjs-table-card" aria-label="Daftar peserta">
+  <header class="bpjs-table-title">
+    <div>
+      <h2 class="bpjs-table-title__heading">Daftar peserta</h2>
+      <p class="bpjs-table-title__description">Data peserta aktif</p>
+    </div>
+  </header>
+  <div class="bpjs-table-scroll">
+    <table class="bpjs-table">
+      <thead>
+        <tr><th scope="col">Nama</th><th scope="col">Kelas</th></tr>
+      </thead>
+      <tbody>
+        <tr><td>Budi Santoso</td><td>Kelas I</td></tr>
+      </tbody>
+    </table>
+  </div>
+</section>
+```
+
+- Use real `<th scope="col">` and `<td>` cells, so screen readers can read the table.
+- Checkbox column: put `class="bpjs-table__check"` on the header and cell, and an `<input type="checkbox">` with an `aria-label`.
+- The table scrolls sideways inside `.bpjs-table-scroll` on narrow screens.
+- Empty state: replace the rows with one row that holds `.bpjs-empty-state`, with a title and a description.
+- Sort: use a `<button class="bpjs-table__sort">` in the header cell.
+
+### File Upload
+
+A drop zone for choosing files, and a row that shows each file's upload progress.
+
+```html
+<div class="bpjs-form-item">
+  <label class="bpjs-form-item__label" for="dokumen">Dokumen</label>
+  <div class="bpjs-file-upload">
+    <label class="bpjs-file-upload__zone">
+      <input class="bpjs-file-upload__input" id="dokumen" type="file" accept=".pdf,.png,.jpg,.jpeg" />
+      <span class="bpjs-file-upload__icon" aria-hidden="true"><svg class="bpjs-icon"><use href="icons.svg#upload"></use></svg></span>
+      <span class="bpjs-file-upload__title"><span class="bpjs-file-upload__action">Klik untuk mengupload</span> atau drag file</span>
+      <span class="bpjs-file-upload__hint">PDF, PNG atau JPG file (Max. 2MB)</span>
+    </label>
+  </div>
+</div>
+
+<div class="bpjs-file-row bpjs-file-row--uploading" aria-live="polite">
+  <span class="bpjs-file-row__name">surat.pdf</span>
+  <span class="bpjs-file-row__meta">
+    <span>12 KB of 20 KB</span>
+    <span aria-hidden="true">|</span>
+    <span class="bpjs-file-row__status">Uploading</span>
+    <span class="bpjs-file-row__percent">50%</span>
+  </span>
+  <span class="bpjs-file-row__bar" role="progressbar" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100" aria-label="Progres unggah surat.pdf">
+    <span style="--bpjs-file-progress: 50%"></span>
+  </span>
+</div>
+```
+
+- The drop zone's input is visually hidden but still focusable. The label is the visible target, so clicking it opens the file picker.
+- Disabled: `disabled` on the input.
+- File row states: `bpjs-file-row--uploading`, `bpjs-file-row--completed` and `bpjs-file-row--failed`. A failed row shows a `bpjs-file-row__retry` button ("Mulai ulang").
+- Your code must set `--bpjs-file-progress` and `aria-valuenow` as the upload moves, and switch the state class when it finishes or fails. The rows are not wired to uploads.
+
+None of the new components ship JavaScript. Your code must update the selected Segmented item (`aria-pressed` and the active class) and the current Pagination page (`aria-current`) when the user changes them.
+
+### Date Picker and Time Picker
+
+Not built yet. Figma's Date Picker and Time Picker pages are empty, so there is no layout to match. The calendar components on other Figma pages may be parts of the Date Picker, but this is not confirmed.
+
+## Icons
+
+There are 154 monochrome icons from Figma's Assets / Icons. Brands, Miscs and Layanan are not included yet. Each icon uses `currentColor`, so it takes the text color around it.
+
+Import only the icons you use. Bundlers drop the rest:
+
+```js
+import { arrowRight, close } from "@bpjs/design-system/icons";
+
+button.innerHTML = `${close}<span>Tutup</span>`;
+```
+
+To look up an icon by its Figma name, use the map entry. It includes every icon:
+
+```js
+import { icon } from "@bpjs/design-system/icons/map";
+
+icon("arrow-right"); // inline SVG markup
+```
+
+Without a bundler, use the sprite. Serve `icons.svg` from the same origin as the page:
+
+```html
+<svg class="bpjs-icon bpjs-icon--lg" aria-hidden="true"><use href="icons.svg#close"></use></svg>
+```
+
+Sizes: `bpjs-icon--xs` (12px), `--sm` (16px), `--md` (20px, default), `--lg` (24px), `--xl` (32px).
+
+Icons are decorative by default. For an icon-only control, put `aria-label` on the button.
+
+## JavaScript API
+
+```js
+import {
+  init,
+  initModals,
+  openModal,
+  closeModal,
+  initControls,
+  setIndeterminate,
+} from "@bpjs/design-system";
+
+const teardown = init(document); // wires every data-bpjs-* trigger and the form controls; returns a cleanup function
+openModal("confirm-delete", { trigger: deleteButton });
+closeModal("confirm-delete", "confirm");
+setIndeterminate(selectAll, true);
+teardown();
+```
+
+- `init(root)` calls `initModals` and `initControls`. Use the individual functions if you need only one.
+- `setIndeterminate(input, value)` sets the mixed state on a checkbox. It only accepts `<input type="checkbox">`.
+
+The package has no runtime dependencies and no network calls. Nothing is sent anywhere.
+
+## Browser support
+
+Chrome and Edge 111+, Firefox 121+, Safari 16.4+. Firefox 121 is the minimum because the form controls use `:has()` to read their state from the input.
+
+## Accessibility
+
+- Components use native elements (`button`, `dialog`, `label`, `input`) where possible.
+- Icon-only buttons need an `aria-label`. Decorative icons are hidden from assistive tech.
+- Switches need a label. Use `bpjs-sr-only` for a label the design does not show.
+- Automated checks catch only part of WCAG 2.1 AA. Full conformance still needs manual testing with assistive technology and an expert review.
+
+## Known gaps
+
+These come from the Figma file. The tokens and icons are unchanged until the design file is updated.
+
+### Font weight
+
+Figma defines a Black (900) weight, but Plus Jakarta Sans stops at 800, so 900 renders as 800.
+
+### Native controls
+
+Components give their buttons, inputs, selects and textareas the design font. Native controls outside the components keep the browser font unless you set `font: inherit` on them. A custom control you build yourself needs `font: inherit` or the design font.
+
+### Table data
+
+The Table is a native `<table>` with the layout and styles only. Sorting and row selection are not wired to data, so your code must handle them. The Table scrolls sideways on narrow screens.
+
+### Swiper
+
+The Swiper is only the position indicator. The carousel itself is not part of this library.
+
+### Pill icon
+
+Figma's Pills have a 16px leading icon. The export for that glyph failed, so the examples use `check` as a placeholder. The active pill with its count badge is about 99px wide, against Figma's 90px. Most of the difference is the count badge, which is about 27px wide here and 20px in Figma. Inactive pills show a count badge too, as in Figma. The Radio Pill is 72px in Figma and 72px here.
+
+### Avatar status
+
+At the XS and SM sizes, the badge count is 9px inside a 12px circle, and the icon status uses a generic user glyph. Both follow Figma's sizes. The glyph may change in a later design update.
+
+### File Upload
+
+The drop zone and file row are both built, but the file row is not tied to a real upload. Your code must update its progress and state.
+
+### Badge widths
+
+Badges size to their content. In Figma, labeled badges range from 44px to 102px wide, and icon-only badges are 22, 24 or 28px. Figma's labeled badges with the same text are not all the same width, and the design file does not explain why. Our badges size to their text, so they may not match Figma's widths exactly.
+
+### Contrast
+
+Some Figma text colors fail WCAG AA (4.5:1 for normal text) on white or on tinted backgrounds, such as pills, badges and the gray track. The tokens are unchanged because they come from the design file:
+
+| Token | Value | Contrast | Where it appears |
+| --- | --- | --- | --- |
+| `--bpjs-text-very-low` | `#adadad` on white | 2.24:1 | Disabled placeholders and Subtitle, Body and Note levels |
+| `--bpjs-text-low` | `#909090` on white | 3.19:1 | Disabled labels and captions, Note and Body levels |
+| `--bpjs-text-warning` | `#c88629` on white | 3.04:1 | Warning text |
+| `--bpjs-text-success` | `#009736` on white | 3.83:1 | Success text |
+| `--bpjs-text-medium` on `--bpjs-background-medium` | `#737373` on `#f4f4f4` | 4.31:1 | Inactive Pill labels, Avatar text, Table avatar initials, inactive Segmented label |
+| `--bpjs-text-success` on `--bpjs-background-success-soft` | `#009736` on `#eaf7ef` | 3.47:1 | Hard Success badge label |
+| `--bpjs-text-warning` on `--bpjs-background-warning-soft` | `#c88629` on `#fcecd6` | 2.62:1 | Hard Warning badge label |
+| `--bpjs-text-danger` on `--bpjs-background-danger-soft` | `#e60400` on `#fdeded` | 4.22:1 | Hard Danger badge label |
+| `--bpjs-text-success` on white | `#009736` on `#fdfdfd` | 3.83:1 | File Upload "Selesai" status |
+
+`text-medium` (4.74:1) and `text-danger` (4.79:1) on white pass. Until the design file darkens the failing colors, avoid them for text people need to read. They are fine for decoration, or for disabled controls, which WCAG exempts.
+
+## License
+
+UNLICENSED for now, so no use rights are granted until a license is chosen. The bundled Plus Jakarta Sans font is licensed under the SIL Open Font License 1.1 (`dist/fonts/OFL.txt`).