<img src="https://bioleyl.github.io/jlib/syware-logo.png" alt="SyWare" height="48">
# jlib
A component library on [Jadis](https://github.com/bioleyl/jadis) and native Web Components, organised in atomic
design: tags that work in any page, typed classes for JSX, form fields that submit like native ones, and a bundle
that holds only the components an app uses. Made by SyWare, for SyWare's own apps, and free for anyone to use.
The documentation site, https://bioleyl.github.io/jlib/ (or `npm run dev`), explains the library and shows every
component with a live playground, examples and its API.
## Install
```bash
npm install @syware/jlib @jadis/core
```
## Use
As HTML tags: define what the page writes (naming the classes keeps them in the bundle).
```ts
import { define, JlButton, JlInput } from '@syware/jlib';
define(JlButton, JlInput);
```
```html
<jl-input name="email" type="email" placeholder="you@example.com"></jl-input>
<jl-button variant="primary" label="Subscribe"></jl-button>
```
In JSX with Jadis (`"jsxImportSource": "@jadis/core"`), the classes are typed:
```tsx
import { JlButton } from '@syware/jlib';
<JlButton variant="primary" icon="plus" label="New project" />;
```
From code, inputs are change handlers and outputs typed events:
```ts
const button = new JlButton();
button.label.set('Save');
button.events.register('press', () => save());
```
## Components
- **Atoms**: app icon, avatar, badge, button, checkbox, chip, divider, icon, input, kbd, link, loading bar,
progress, progress ring, rating, select, skeleton, slider, spinner, switch, textarea.
- **Molecules**: accordion, accordion item, account button, alert, avatar group, breadcrumb, calendar, card, chip
group, code block, combobox, copy button, date picker, empty state, facts, field, file drop, input list, list
item, load more, load state, menu, number input, pagination, popover, radio group, search, search button,
segmented control, stat, steps, tab panel, tabs, tag input, timeline, toast, tooltip.
- **Organisms**: command palette, confirm, dialog, drawer, flow, navbar, page header, page outlet, side nav, tab
bar, table, toaster, tree.
- **Templates**: app shell, auth layout, page, split view, stack.
## Icons
Components draw their own icons with no setup. The names a page writes (`<jl-icon name="settings">`,
`icon="plus"` on a button) are registered once, so a bundle holds only the icons in use: Icons are
[lucide](https://lucide.dev)'s: an app that imports some by name installs it itself (`npm install lucide`), as a
strict package manager (pnpm) gives an app only the packages it names.
```ts
import { Coffee } from 'lucide';
import { COMMON_ICONS, registerIcons } from '@syware/jlib';
registerIcons({ coffee: Coffee }); // one by one, from lucide
registerIcons(COMMON_ICONS); // or the ~90 usual ones (about 5 kB)
```
## Theming
Every colour, radius and size is a CSS custom property (`--jl-*`), defined in the `jlib` cascade layer: a plain rule
of the page overrides it. Light and dark follow the system; `data-theme="light|dark"` on any element decides for that
part of the page.
```css
:root {
--jl-accent: #6d4ed8;
}
```
## Vibe coding
Two skills teach coding agents to build on jlib: `jlib-official`, the components (each one's whole API, offline),
the way an app is written on them, the mistakes agents make and a self-check; and `syware-ux`, how SyWare's apps
behave, every UX pattern in full and the checklist a page is reviewed against. They build on Jadis's skill,
`jadis-official`. Install them in one of three ways:
- **Claude Code**, as plugins that update with each release; `syware-ux` brings `jlib-official`, which brings
`jadis-official` (for an app that does not follow SyWare's UX, install `jlib-official@jlib`):
```
/plugin marketplace add bioleyl/jadis
/plugin marketplace add bioleyl/jlib
/plugin install syware-ux@jlib
```
- **Any agent**, with [skills.sh](https://skills.sh) (Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot,
OpenCode…):
```bash
npx skills add bioleyl/jlib
npx skills add bioleyl/jadis
```
- **Any agent**, with the install script, which asks which skills and where: `~/.agents/skills`, `~/.claude/skills`,
the project's `.agents/skills` or `.claude/skills`, or another folder (`--help` for the options):
```bash
curl -fsSL https://raw.githubusercontent.com/bioleyl/jlib/main/install-skill.sh | sh
```
The skills are in [plugins/](plugins): [jlib-official](plugins/jlib-official/skills/jlib-official/SKILL.md) and
[syware-ux](plugins/syware-ux/skills/syware-ux/SKILL.md). How a team shares them and how to ask well: the site's
[Vibe coding](https://bioleyl.github.io/jlib/vibe-coding) page.
## Development
```bash
npm install
npm run dev # the documentation site, with hot reload
npm run check # generated files up to date, lint, types, unit tests
npm run test:e2e # builds the site and checks every page in a headless Chromium
npm run build # the library (dist/), the size report, the site (site/dist/)
npm run size # what each component adds to a bundle
```
`src/index.ts` and `src/all.ts` are generated from the component folders, and the plugins' lists of components and
patterns from their documentation pages: run `npm run generate` after adding a component or a pattern. Conventions for contributors are in [AGENTS.md](AGENTS.md).
## Releasing
```bash
npm version patch
```
```bash
git push --follow-tags
```
Then a maintainer starts **Publish to npm** in the Actions tab for the tag (`gh workflow run publish.yml -f
tag=vX.Y.Z`): it stages the version on npm and creates the GitHub release, and they approve it with
`npm stage approve`. Every step, pre-releases and what to do when something fails: [RELEASING.md](RELEASING.md).
What changed in each version: [CHANGELOG.md](CHANGELOG.md).
## Made by SyWare
jlib is the component library behind SyWare's apps, and it carries their look. SyWare makes it for its own products
and shares it: use it in yours, change it, ship it. The official SyWare logo is in `site/public/` as SVG:
`syware-logo.svg`, `syware-logo-dark.svg` for dark backgrounds, and `syware-mark.svg` for the mark alone.
## License
MIT, © SyWare: free to use, change and distribute. See [LICENSE](LICENSE).