Get started

Is Lyotic for this?

Use Lyotic when all three are true.

• Work is delegated. An agent or automation reads, proposes or changes things on someone’s behalf.
• The truth lives elsewhere. Several systems each hold part of the state (an ERP, a store, a repository, a ledger) and they can disagree.
• Effects matter. Some actions are hard to undo, touch other people, or cost money.

If the product is a chat that only answers questions, Lyotic is more than you need. For products that change inventory, merge code, file documents or send payments, use the contract to connect the representation to the real execution boundary.

The five ideas to hold

1. The Work Case is the unit. Not a message, not a screen. A persistent piece of work with a goal, a scope, an owner and a revision. Meaning model
2. State has independent axes. Epistemic, freshness, authority, execution, control, verification. Applied is an execution state; verified is a verification state. They never merge. State axes
3. Authority has five layers. Capability, permission, delegation, approval, validity at execution. Authority
4. A resolver decides the form. resolve(state) → plan. The plan says which representation, what must be shown, which controls exist and which words are forbidden. Representation
5. Motion explains, it never decorates. One surface morphs between representations; the system never moves your focus to ask for attention. Motion

For designers

Start with the status language and the Work Object Shell. Then read each component’s may claim / must not claim contract before placing it: a component that says more than its evidence breaks Lyotic even if it looks right.

• Design states, not screens. For each Work Object, list the axis values it can be in, then check which representation the resolver gives each combination.
• Use amber only for what a person must judge. Green only for a verified scope. Nothing else earns either.
• Keep controls where they are through a morph. A button must never become a different action under the pointer.
• Tokens are in packages/tokens/dist/tokens.json (DTCG) for Figma variables. Semantic roles are separate from brand values, so you can re-skin without changing meaning.

For engineers

No framework and no build step. Serve the repository and open /site/, or import the packages directly.

git clone https://github.com/yejuntak/Lyotic-design-system
cd Lyotic-design-system
git checkout claude/amazing-keller-951le1  # until PR #1 merges into main
npm install
npm test          # the reference case as a test suite
npm run serve     # then open http://localhost:4173/site/

<link rel="stylesheet" href="packages/tokens/dist/lyotic.css">
<link rel="stylesheet" href="packages/morph/src/morph.css">
<link rel="stylesheet" href="packages/components/src/components.css">

<div id="case"></div>
<script type="module">
  import { resolve } from './packages/core/src/index.js';
  import { WorkObjectShell } from './packages/components/src/index.js';

  const shell = new WorkObjectShell(document.getElementById('case'));
  const render = (state, initiator = 'system') => shell.render(state, resolve(state), { initiator });

  render(initialState);
  source.subscribe((next) => render(next));            // system-initiated: no focus change
  document.addEventListener('ly-action', (e) => executor.request(e.detail)); // re-validated there
</script>

Your application owns the Case state and the executor. Lyotic owns the representation. Read Develop for the package APIs and the invariant harness.

For researchers

Lyotic is built to be evaluated, not assumed. The resolver is deterministic, so the representation can be varied while inputs stay fixed. Start with Evaluation and Research lineage. A fixed, well-built supervisory interface winning some tasks is a finding, not a failure.