Metadata-Version: 2.5
Name: abilian-ds
Version: 0.3.0
Summary: Abilian Design System — a closed token vocabulary for Litestar and Jinja
Project-URL: Homepage, https://ads.lab.abilian.com
Project-URL: Documentation, https://ads.lab.abilian.com
Project-URL: Source, https://github.com/abilian/abilian-ds
Project-URL: Issues, https://github.com/abilian/abilian-ds/issues
Project-URL: Changelog, https://github.com/abilian/abilian-ds/blob/main/CHANGES.md
Author-email: Stefane Fermigier <sf@abilian.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: accessibility,css,design-system,design-tokens,jinja,litestar
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Topic :: Text Processing :: Markup :: HTML
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# Abilian Design System

This is a design system for business applications built on **Litestar and Jinja**, written in plain CSS with no front-end toolchain. A small set of knobs is the whole overridable surface; everything else is derived from them.

[Documentation](https://ads.lab.abilian.com) · [Token and class reference](https://ads.lab.abilian.com/reference/components/) · [llms.txt](https://ads.lab.abilian.com/llms.txt)

```bash
pip install abilian-ds     # or: uv add abilian-ds
abilian-ds sync
```

It has no runtime dependencies and needs no build step.

## The idea

Styling goes through a **closed vocabulary**: a `--ads-*` custom property or an `ads-*` class. There is no utility layer, no arbitrary-value syntax and no `style=` attribute. `bg-gray-100`, `p-4` and `text-[13px]` generate no CSS at all, and `abilian-ds lint` rejects them before they can sit in a template looking plausible.

That closure is what makes the rest possible:

- **Knobs are the overridable surface; everything else derives.** Set `--ads-brand` and its hover, active, tint, border and foreground shades follow. Set `--ads-space-scale` and every padding, gap, margin and control height follows. One declaration on `:root` changes 361 of 501 elements on a page.
- **Both themes in one value.** Every colour holds light and dark through `light-dark()`. There is no `dark:` variant anywhere and so no second styling pass to forget.
- **State that a person can perceive is an attribute.** The current item is `aria-current`, a toggle is `aria-pressed`, an invalid field is `aria-invalid`. The stylesheet keys off those, so the look cannot exist without the meaning.
- **Measured parity with [Tabler](https://tabler.io).** A harness compares the two property by property and reports **0 differences**.
- **Accessibility with tests behind it**: contrast in both themes, reflow at 320px, 200% text-only zoom, keyboard traversal, pointer target size and Windows high contrast, swept across every route on every run.

## What `sync` gives you

```
static/css/ads/ads.css     the stylesheet — one file, one request
static/css/ads/shell.js    what the dropdowns, drawers and theme toggle need
static/css/ads/situ.css    only if you use situ
templates/ads/shell.html   the application frame, extended not copied
templates/ads/nav.html     navigation rendered from data
templates/ads/form.html    field, select, textarea, checkbox, button macros
```

Paths live in `[tool.abilian-ds]` in your `pyproject.toml`, so the commands take no flags:

```toml
[tool.abilian-ds]
templates = ["templates"]
prefix = "ads-"
```

## A page

```jinja
{% extends "ads/shell.html" %}
{% block title %}Contacts · Acme{% endblock %}
{% block brand_name %}Acme{% endblock %}
{% block heading %}Contacts{% endblock %}
{% block actions %}<button class="ads-btn ads-btn--primary">New contact</button>{% endblock %}
{% block body %}
<div class="ads-card"><div class="ads-card__body ads-stack">
  <div class="ads-cluster">
    <span class="ads-avatar ads-avatar--sm">AR</span>
    <strong class="ads-truncate">Amélie Rousseau</strong>
    <span class="ads-badge ads-tone-success">active</span>
  </div>
</div></div>
{% endblock %}
```

The navigation is data, because markup drifts:

```python
nav = [{"section": "Directory",
        "items": [{"href": "/contacts", "label": "Contacts", "icon": "users"}]}]
```

Configure Jinja with `undefined=StrictUndefined`. It turns a misspelt component argument into an error, where it would otherwise yield an unstyled element.

## The commands

| command | what it does |
|---|---|
| `abilian-ds sync` | vendor the stylesheet, the shell script and the macros into your project |
| `abilian-ds lint` | check templates against the design system |
| `abilian-ds tokens` | regenerate `TOKENS.md` from the stylesheet |

`lint` is the contract. Green means on-system:

```
templates/page.html:1: unknown-class: bg-gray-100: not in the design system
templates/page.html:2: dark-variant: dark:text-white: colours carry both themes, there is no dark pass
templates/page.html:2: arbitrary-value: text-[13px]: bypasses the token scale
templates/page.html:2: inline-style: style='color: red': a decision belongs in CSS
```

It also hashes every vendored file against what the package would produce, so a local edit to `ads.css` shows up as a finding.

## What it does not do

- **No icon set.** The shell uses an `icon()` Jinja global if you register one; an icon set is a licence you cannot change once it is baked in. [How to wire one up.](https://ads.lab.abilian.com/getting-started/first-page/)
- **No JavaScript framework.** `shell.js` is a page of delegated event handlers with no dependencies. Components that need more (a rich data grid, a live region) are [situ](https://situ.hop3.abilian.com)'s job, and `situ.css` bridges the two palettes.
- **No CSS-in-JS, no theme builder UI, no component library for React.** This is Jinja and CSS.

## Status

Beta. The vocabulary, the linter and the shell are stable enough to build on; the 0.x version number covers the rest. See [CHANGES.md](CHANGES.md).

## Licence

Apache 2.0. Copyright © 2026 Abilian SAS.
