Overview
@ttoss/fsl-ui is the React implementation of the FSL component model: a component library built on React Aria Components where every component declares a formal semantic identity — its Entity — and that identity determines which @ttoss/fsl-theme tokens it may consume. Authors choose meaning (evaluation, consequence, composition); the theme chooses appearance. The package ships an AI-readable contract (llms.txt and src/tokens/CONTRACT.md in the published tarball) so that agents generate semantically correct UI on the first pass.
Composition guidelines
The Entity contract guarantees that a UI is semantically correct — the right token for the right meaning, consistent across theme and mode. It does not, on its own, guarantee that the result is well designed. Correctness and beauty are orthogonal: a screen where every component is legal can still read as an undifferentiated pile of controls. These guidelines close that gap. They are the taste layer — the small set of composition decisions that make the default projection look like a considered product, not a form dump.