Get started with Agentica

DémarrerGet started

Adopter Agentica, c'est consommer des décisions — pas des valeurs. Trois niveaux de tokens, 14 composants, six plateformes de sortie, le tout auditable WCAG 2.2. Adopting Agentica means consuming decisions — not values. Three token levels, 14 components, six output platforms, all WCAG 2.2 auditable.

Voir les 3 étapes ↓See the 3 steps ↓ Copier starter-kit →Copy starter-kit →

Démarrage rapideQuickstart

Disponible sur npm (v0.x)Available on npm (v0.x) @agentica-ds/tokens et @agentica-ds/components sont publiés — API encore susceptible d'évoluer avant la 1.0. @agentica-ds/tokens and @agentica-ds/components are published — API may still evolve before 1.0.

Le code complet, sans explication (le détail de chaque étape suit plus bas)The full code, no explanation (the detailed walkthrough follows below)

npm install @agentica-ds/tokens @agentica-ds/components lit

import '@agentica-ds/tokens/css';
import '@agentica-ds/components';

<agtc-button variant="primary">Save</agtc-button>

Ce que vous obtenezWhat you get

Trois niveaux, un contratThree levels, one contract

Tokens à 3 niveaux3-level tokens

Primitif → sémantique → composant. Les valeurs sont séparées des intentions — lisibles par les humains et les agents.Primitive → semantic → component. Values are separated from intentions — readable by humans and agents.

14 composants14 components

Web Components framework-agnostic (Lit), ou classes CSS. Chaque composant est un contrat, pas une suggestion.Framework-agnostic Web Components (Lit), or CSS classes. Each component is a contract, not a suggestion.

6 plateformes6 platforms

CSS, JS, Tailwind, Angular, iOS, Android — une seule source de vérité, compilée partout.CSS, JS, Tailwind, Angular, iOS, Android — one source of truth, compiled everywhere.

Trois étapesThree steps

De zéro à intégréFrom zero to integrated

InstallerInstall

Les paquets sont publiés sur le registre npm public. lit est une dépendance pair des composants. The packages are published on the public npm registry. lit is a peer dependency of the components.

npm install @agentica-ds/tokens @agentica-ds/components lit

# angular/ios/android outputs aren't published to npm yet — clone the repo
# and use dist/tokens/{angular,ios,android}/ for those platforms:
# git clone https://github.com/gnegreiros-ux/agentica-design-system.git

2
Importer et consommer les variables CSSImport and consume the CSS variables
Chargez la feuille de tokens, puis référencez les variables sémantiques par leur intention. C'est l'approche que ce site lui-même utilise. Load the token sheet, then reference semantic variables by their intent. This is the approach this very site uses.

Avec un bundlerWith a bundler
```
/* Bundler (Vite, Webpack, esbuild…) */
import '@agentica-ds/tokens/css';
import '@agentica-ds/tokens/css/dark'; /* dark mode support */
```
Sans bundler (HTML pur)No bundler (plain HTML)
```

<link rel="stylesheet" href="node_modules/@agentica-ds/tokens/css/all.css">
<link rel="stylesheet" href="node_modules/@agentica-ds/tokens/css/dark.css">
```
Puis, dans les deux cas — utilisation par intentionThen, either way — usage by intent
```
/* Consume by INTENT — never hardcode values */
.cta {
  background: var(--agtc-semantic-color-action-primary);
  color:      var(--agtc-semantic-color-text-on-action);
  padding:    var(--agtc-semantic-space-control-padding-y)
              var(--agtc-semantic-space-control-padding-x);
  border-radius: var(--agtc-semantic-radius-control);
}
```
OptionnelOptional
Mode sombre (dark mode)Dark mode
Chargez dark.css après all.css (déjà fait ci-dessus si vous avez suivi l'exemple bundler). Ce fichier contient les 38 tokens qui changent de valeur en mode sombre, sous le sélecteur [data-theme="dark"]. Ajoutez ensuite l'attribut sur <html> et pilotez-le avec un toggle JS. Load dark.css after all.css (already done above if you followed the bundler example). This file contains the 38 tokens that change value in dark mode, under the [data-theme="dark"] selector. Then add the attribute on <html> and drive it with a JS toggle.
```

<html data-theme="dark">


<html data-theme="light">
```
```
// Read the stored preference or the system preference
const stored = localStorage.getItem('agtc-theme');
const preferred = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
document.documentElement.setAttribute('data-theme', stored ?? preferred);

// Toggle on click
toggleBtn.addEventListener('click', () => {
  const next = document.documentElement.getAttribute('data-theme') === 'dark' ? 'light' : 'dark';
  document.documentElement.setAttribute('data-theme', next);
  localStorage.setItem('agtc-theme', next);
});
```
Composants à fond toujours sombreAlways-dark background components Les composants glassmorphism ou overlay qui restent sombres quel que soit le thème de la page (ex: cartes hero, modales sombres) doivent utiliser text.on-dark — et jamais text.primary. text.primary est adaptatif (sombre en light, clair en dark) : sur un fond fixement sombre, le contraste peut tomber à 1.12:1. Glassmorphism or overlay components that stay dark regardless of page theme (e.g. hero cards, dark modals) must use text.on-dark — never text.primary. text.primary is adaptive (dark in light mode, light in dark mode): on a fixed dark background, contrast can drop to 1.12:1.
```
/* Component with an always-dark background (glassmorphism, overlay):
   use text.on-dark, NOT text.primary */
.card-glass .title {
  color: var(--agtc-semantic-color-text-on-dark);          /* ✅ */
  /* color: var(--agtc-semantic-color-text-primary); */    /* ❌ contraste insuffisant */
}
```
3
Utiliser les Web ComponentsUse the Web Components
Montez les Web Components agtc-*. Ils portent les contrats comportementaux — par exemple, critical exige une confirmation. Mount the agtc-* Web Components. They carry behavioural contracts — e.g. critical requires confirmation.

ImportImport
```
// Everything at once (barrel)
import '@agentica-ds/components';

// Or one component at a time (tree-shaking)
import '@agentica-ds/components/agtc-button.js';
```
UtilisationUsage
```
<agtc-button variant="primary">Save</agtc-button>
<agtc-button variant="critical">Delete folder</agtc-button>
```

La règle d'orThe golden rule Jamais de valeur en dur. Toujours via un token sémantique. Cette indirection est ce qui rend vos décisions applicables par des agents IA — sans interprétation. Voir les trois niveaux → Never a hardcoded value. Always through a semantic token. This indirection is what makes your decisions applicable by AI agents — without interpretation. See the three levels →

FrameworksFrameworks

Intégration par frameworkFramework integration

Optionnel — uniquement si vous utilisez Angular, Vue ou React. Les composants sont des Web Components natifs ; sinon, passez directement aux plateformes de sortie. Optional — only if you use Angular, Vue, or React. Components are native Web Components; otherwise, skip straight to output platforms.

Angular

Configuration requise : ajoutez CUSTOM_ELEMENTS_SCHEMA au module (ou aux schemas d'un composant standalone). Le binding de propriétés et d'événements est ensuite natif. Required configuration: add CUSTOM_ELEMENTS_SCHEMA to the module (or to a standalone component's schemas). Property and event binding is then native.

// app.module.ts (NgModule) — or on a standalone component
@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

Le pipeline Style Dictionary génère aussi un thème Material Angular M3 à partir des mêmes tokens — clone-only, pas publié sur npm (voir le tableau des plateformes de sortie plus bas). The Style Dictionary pipeline also generates a Material Angular M3 theme from the same tokens — clone-only, not published to npm (see the output-platforms table below).

// theme.scss — Material M3 theme generated from the same tokens
// (clone-only — dist/tokens/angular/, not published to npm)
@use "dist/tokens/angular/m3-theme" as *;
@use "@angular/material" as mat;

$theme: mat.define-theme((
  color: (primary: $agtc-primary-palette, theme-type: light),
));

Vue

Configuration requise : déclarez le préfixe agtc- comme élément personnalisé dans la config du compilateur, pour que Vue ne tente pas de le résoudre comme un composant Vue. Required configuration: declare the agtc- prefix as a custom element in the compiler config, so Vue doesn't try to resolve it as a Vue component.

// vite.config.js
export default {
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith('agtc-'),
        },
      },
    }),
  ],
};

React

Configuration requise : aucune en React 19+ (support natif). Avant 19, les attributs simples fonctionnent déjà nativement — seules les propriétés complexes (objets, tableaux) nécessitent une assignation via ref. Required configuration: none on React 19+ (native support). Before 19, simple attributes already work natively — only complex properties (objects, arrays) need a ref-based assignment.

// React 19+ — native, no wrapper needed
<agtc-button variant="primary">Save</agtc-button>

// React < 19 — simple (string/boolean) attributes work natively;
// complex properties (objects, arrays) need a ref + property assignment
const tableRef = useRef(null);
useEffect(() => {
  if (tableRef.current) tableRef.current.columns = myColumns;
}, [myColumns]);

<agtc-table ref={tableRef}></agtc-table>

Vanilla / Other

Configuration requise : aucune — import direct, comportement natif du navigateur. Required configuration: none — direct import, native browser behavior.

Plateformes de sortieOutput platforms

Une source, six ciblesOne source, six targets

Une source JSON, compilée par Style Dictionary vers six cibles. css, js et tailwind sont publiés sur npm — ce sont les seuls formats qu'un projet JS/web installe via un gestionnaire de paquets. angular, ios et android restent clone-only : ce sont des sorties pour des écosystèmes qui ne consomment pas npm (Swift Package Manager, Gradle) — les publier sur npm ne les rendrait pas plus faciles à utiliser. One JSON source, compiled by Style Dictionary to six targets. css, js, and tailwind are published to npm — the only formats a JS/web project installs via a package manager. angular, ios, and android stay clone-only: these are outputs for ecosystems that don't consume npm (Swift Package Manager, Gradle) — publishing them to npm wouldn't make them any easier to use.

CSS

npm

JavaScript

npm

Tailwind CSS

npm

Angular

cloneclone

Swift (iOS)

cloneclone

Android

cloneclone

PlateformePlatform	ImportImport	SourceSource	FormatFormat
`css`	`@agentica-ds/tokens/css`	npm	Variables CSS (custom properties)CSS custom properties
`js`	`@agentica-ds/tokens/js`	npm	Exports ES6ES6 exports
`tailwind`	`@agentica-ds/tokens/tailwind`	npm	Extension de configurationConfig extension
`angular`	`dist/tokens/angular/`	cloneclone	SCSS Material M3Material M3 SCSS
`ios`	`dist/tokens/ios/`	cloneclone	SwiftSwift
`android`	`dist/tokens/android/`	cloneclone	XML (couleurs + dimensions)XML (colors + dimensions)

Agents IAAI agents

Pour les agents IAFor AI agents

Agentica n'est pas qu'une bibliothèque visuelle : c'est un jeu de règles lisibles par machine. Un agent lit les contrats de composants, les règles de gouvernance et les ADRs pour appliquer vos décisions sans improviser — et escalade vers un humain quand c'est requis. Agentica is more than a visual library: it is a machine-readable rule set. An agent reads component contracts, governance rules and ADRs to apply your decisions without improvising — and escalates to a human when required.

Documentation agents →Agent documentation → Explorer les composantsExplore components Code sourceSource code