Skip to main content

FSL Lexicon

The FSL Lexicon is the normative dictionary of the Foundational Semantic Language.

It defines the canonical meanings of the core terms of the language so that components, tokens, themes, tooling, and AI systems can derive from the same semantic base without drift.

This document contains the actual core vocabulary of FSL.

It does not explain how to write lexicons in general. It defines the foundational terms themselves.

What this lexicon covers

This lexicon covers the FSL core only:

  • Entity Kind
  • Structural Role
  • Interaction Kind
  • Composition Role
  • Evaluation
  • Consequence
  • State
  • Layer Role
  • Context Class

This lexicon does not include projection-specific vocabularies such as:

  • token-family domains
  • text scales
  • spacing contracts
  • size contracts
  • boundary contracts

Those belong to derived projection lexicons, not to the FSL core.

Lexical laws

These rules are normative for the core lexicon.

  1. One preferred term, one core meaning.
  2. Context may refine meaning but must not redefine core identity.
  3. Core terms must be defined independently of styling, token paths, or component APIs.
  4. If two terms express materially different meaning, they must remain distinct.
  5. If a meaning belongs only to a downstream projection, it must not enter the FSL core lexicon.

Reading convention

Each entry contains:

  • Term — canonical label
  • Meaning — normative definition
  • Distinguish from — the nearest concepts it must not collapse into

1. Entity Kind

Entity Kind answers:

What kind of interactive thing is this?

Entity Kind is the most stable semantic identity in the language. It is the closest thing FSL has to “what this thing fundamentally is”.

Entity Kinds are pairwise disjoint in the core lexicon.

TermMeaningDistinguish from
ActionAn interactive entity whose primary meaning is to trigger, initiate, confirm, submit, or dismiss an action in the system.Not Navigation (movement across destinations), not Input (value entry), not Feedback (status communication).
InputAn interactive entity whose primary meaning is entering, editing, or manipulating a value directly.Not Selection (choosing among options), not Action (performing an operation).
SelectionAn interactive entity whose primary meaning is choosing one or more options from a set.Not Input in general; some selection UIs may feel input-like, but their semantic core is choice, not arbitrary value entry.
CollectionAn entity whose primary meaning is organizing and presenting sets of items, options, records, or content units.Not Structure in general; Collection is about grouped items as an information set, not just layout/support.
OverlayAn entity whose primary meaning is temporary layered presentation above the base interface.Not Disclosure; Disclosure reveals in place, Overlay creates a layered interaction context.
NavigationAn entity whose primary meaning is moving, orienting, or stepping across destinations, locations, or information spaces.Not Action; a link may look actionable, but its semantic core is movement/orientation, not command execution.
DisclosureAn entity whose primary meaning is revealing or hiding related content in place without creating a separate layered context.Not Overlay; not all show/hide behavior creates a layered surface.
FeedbackAn entity whose primary meaning is communicating state, outcome, condition, warning, success, failure, or system response.Not Action or Overlay; a feedback object may appear inside those, but its identity is communicative, not operational.
StructureAn entity whose primary meaning is organizing, supporting, grouping, separating, or framing content and interaction.Not Collection; Structure is about support/form, Collection is about a set of items as a semantic grouping.

Critical disambiguations

  • Action is not the same as primaryAction. Action is an entity kind. primaryAction is a composition role.

  • Selection is not the same as toggle.binary or select.single. Selection is an entity kind. Those are interaction kinds.

  • Overlay is not the same as blocking. Overlay is an entity kind. blocking is a layer role.


2. Structural Role

Structural Role answers:

What structural function does this part play?

Structural Roles describe semantic topology inside entities and composites.

Unlike Entity Kinds, Structural Roles are not globally disjoint. The same structural role may lawfully appear under different entities.

TermMeaningDistinguish from
rootThe primary semantic container of an entity as a whole.Not just “outer DOM node”; root is the semantic whole of the entity.
controlThe primary interactive part through which the entity is directly operated.Not trigger in general; a trigger invokes another structure, a control may be the entity itself.
surfaceA semantically meaningful containing plane or container that holds content or interaction.Not content; surface is the containing support, content is what is carried.
contentThe main carried content of an entity or composite.Not body in all cases; body is a specific text/content role, content is broader.
labelA naming or identifying part that tells the user what an entity or option is.Not title in general; title is more heading-like, label is directly naming/identifying.
descriptionA supporting explanatory part that clarifies meaning, conditions, or usage.Not status; description explains, status communicates current condition/outcome.
titleA heading-like part that introduces or names a larger content or surface unit.Not label; title organizes a larger unit, label identifies a more immediate one.
bodyThe primary explanatory or descriptive content body of an entity or surface.Not content in general; body is a specific textual/content-bearing role.
actionsA grouped area or region that contains one or more action-bearing parts.Not a single action itself.
statusA part whose function is to communicate condition, progress, success, warning, or error.Not description; status is current condition, description is explanatory support.
iconA compact symbolic or pictorial supporting part.Not indicator; icon may identify or decorate, indicator signals state or choice.
indicatorA part whose role is to signal state, selection, or position.Not icon in general; indicator has a signaling function.
itemA member unit inside a collection or grouped set.Not content in general; item implies membership in a set.
triggerA part whose role is to invoke, open, reveal, or activate another entity or structure.Not control in general; trigger is relational and points to something else.
backdropA layered part positioned between an overlayed structure and the obscured underlying interface.Not surface; backdrop is environmental/layering support, not primary carried surface.
positionerA part whose role is to place or anchor another layered structure spatially.Not generic layout; it is specifically for semantic positioning of another structure.
closeTriggerA trigger whose role is specifically to close or dismiss the current entity.Not every dismiss action; this is specifically a trigger part.
supportingVisualA non-primary visual part that supports recognition, context, or grouping.Not media in general; supportingVisual is subordinate and usually lighter-weight.
trailingMetaA secondary trailing part that carries supporting metadata or contextual detail.Not status; metadata is not necessarily current state.
selectionControlA structural part whose immediate role is selection or toggle operation within a larger entity.Not generic control; this specifically participates in selection semantics.
mediaA part whose role is carrying image, video, illustration, or rich visual media.Not icon; media is richer and semantically broader.
leadingAdornmentA supporting part positioned before the primary control, carrying a visual cue, prefix, or contextual element.Not control; this part is subordinate and does not itself bear the primary interaction.
trailingAdornmentA supporting part positioned after the primary control, carrying a visual cue, suffix, or affordance.Not control; this part is subordinate and contextual.
validationMessageA part whose role is to communicate the outcome of validation for the associated entry or selection.Not status; validationMessage is specific to validation outcome, not general condition.

Critical disambiguations

  • trigger is relational; control is direct. A combobox control is not merely a trigger. A button that opens a dialog is often a trigger.

  • label and title are not synonyms. label identifies an immediate thing. title introduces a larger semantic unit.

  • description and status are not synonyms. description explains. status communicates current condition.


3. Interaction Kind

Interaction Kind answers:

What kind of interaction is being expressed?

Interaction Kind is fundamental because interactive meaning cannot be recovered safely from structure alone.

TermMeaningDistinguish from
commandAn interaction that issues an operation or command without primarily representing navigation, value entry, or selection.Not navigate.link, not entry.text, not select.single.
confirmAn interaction that explicitly affirms, commits, or accepts a pending operation or state transition.Not generic command; confirm is a committing subtype of action.
dismissAn interaction that closes, cancels, exits, or retreats from the current interaction path.Not secondary or muted; dismiss is not an emphasis level.
entry.textAn interaction centered on entering or editing free-form text.Not entry.value in general; text is one subtype of value entry.
entry.valueAn interaction centered on entering or manipulating a value, not necessarily text.Broader than entry.text.
select.singleAn interaction that chooses exactly one option from a set.Not select.multi or toggle.binary.
select.multiAn interaction that chooses more than one option from a set.Not select.single.
toggle.binaryAn interaction that switches between two discrete states.Not toggle.tristate.
toggle.tristateAn interaction that can lawfully occupy three states, including an indeterminate or partial state.Not toggle.binary.
navigate.linkAn interaction whose primary function is movement to another destination or location.Not command; even if visually button-like, its semantic core is navigation.
navigate.stepAn interaction whose function is progression between stages, screens, or ordered steps.Not general navigation across arbitrary destinations.
disclose.toggleAn interaction that reveals or hides related content in place.Not an overlay entity's open/close — that is modeled at the Entity layer.
status.passiveA communicative condition that informs without demanding immediate user action.Not status.interruptive.
status.interruptiveA communicative condition that interrupts, escalates, or demands immediate handling.Not passive informational status.

Critical disambiguations

  • confirm is not just a “primary button”. It is an interaction kind with commitment semantics.

  • dismiss is not just a low-emphasis button. It is an interaction kind with retreat/close semantics.

  • popup.* kinds exist to prevent collapsing all popup behavior into one ambiguous bucket.


4. Composition Role

Composition Role answers:

What role does this entity or part play inside a larger composition?

Composition Role is relational. It never replaces Entity Kind.

TermMeaningDistinguish from
primaryActionThe main forward, commit, or preferred action path within a composition.Not Action itself; this is a compositional role, not an entity kind.
secondaryActionA subordinate but still intentional action path within a composition.Not dismissAction; secondary is not necessarily exit/cancel.
dismissActionAn action whose role is to cancel, close, back out, or safely dismiss the current flow.Not generic secondaryAction; dismiss is semantically specific.
headingA compositional role introducing the primary heading of a larger unit.Not generic title in every context; this is relational to a composition.
bodyA compositional role carrying the main explanatory or substantive content of a larger unit.Not generic content; not the same as body Structural Role — in Composition, this designates the slot, not the part itself.
statusA compositional role carrying state, outcome, or condition communication within a composition.Not generic description; not the same as status Structural Role — in Composition, this designates the slot, not the part itself.
controlA compositional role designating where the primary control-bearing child belongs.Not the same as control Structural Role; in Composition, this names the slot, not the part itself.
labelA compositional role designating where a naming/label child belongs.Not the same as label Structural Role; in Composition, this names the parent-side slot.
descriptionA compositional role designating where a descriptive child belongs.Not the same as description Structural Role; in Composition, this names the parent-side slot.
supportingA compositional role designating where a supporting child belongs.Broader than specific label/description/status slots.
selectionA compositional role designating where a selection-bearing child belongs.Not the same as selectionControl Structural Role; in Composition, this names the slot.

Critical disambiguations

  • Structural roles describe the part itself.
  • Composition roles describe what that part means in relation to a larger composition.

This distinction is mandatory.


5. Evaluation

Evaluation answers:

What evaluative or emphatic meaning does this expression carry?

Evaluation is not styling and not token choice. It is semantic emphasis or valence.

Evaluation is a discriminated union of two decision classes — an expression carries one or the other, never both:

  • Emphasis (primary, secondary, accent, muted) — intensity within the default semantic context.
  • Valence (positive, caution, negative) — semantic outcome meaning. A valence implies its own emphasis; intensity within a valence is expressed by other dimensions (e.g. Structural Role), not by combining emphasis with valence.
ClassTermMeaningDistinguish from
EmphasisprimaryThe main intended emphasis in a semantic context.Not “blue”, “bold”, or any visual style.
EmphasissecondaryA secondary but still intentional emphasis relative to the same context.Not equivalent to dismiss, muted, or less important in every case.
EmphasisaccentA deliberately differentiated emphasis used to highlight meaningful distinction from the default emphasis.Not just “more colorful”; accent is semantic divergence.
EmphasismutedA de-emphasized but still meaningful evaluation.Not “disabled”, not “inactive”, not “secondary” in general.
ValencepositiveAn affirming, successful, healthy, or favorable evaluation.Not the same as “success UI token”; this is foundational meaning.
ValencecautionA warning or careful-attention evaluation.Not the same as “negative”; caution signals risk, not necessarily harmful outcome.
ValencenegativeA harmful, erroneous, destructive, or adverse evaluation.Not necessarily destructive consequence; evaluation and consequence are distinct dimensions.

Critical disambiguations

  • negativedestructive negative is evaluative. destructive is consequential.

  • muteddisabled muted still carries meaning. disabled is a state.


6. Consequence

Consequence answers:

What kind of user-facing consequence or risk profile does this interaction carry?

Consequence exists because some meanings materially shape user experience and risk even before styling or implementation.

TermMeaningDistinguish from
neutralNo special consequence or risk profile is implied beyond the baseline interaction.Not the absence of semantics; simply no special risk-bearing consequence.
reversibleThe effect can be undone or reverted without major loss.Not the same as recoverable; reversible means the original change itself can be undone.
committingThe interaction moves the user or system into a more committed state.Not every primary action is committing.
destructiveThe interaction causes deletion, invalidation, or materially harmful loss.Not the same as negative in general.
interruptiveThe interaction or condition interrupts flow and demands immediate or prioritized handling.Not every warning is interruptive.
recoverableA failure or adverse path exists, but recovery is expected to be supported.Not the same as reversible; recoverable may involve repair, not simple undo.
safeDefaultRequiredThe interaction requires the safer option, default, focus, or path to be privileged.Not just “be careful”; this is a semantic requirement on downstream behavior.

Critical disambiguations

  • destructive describes outcome risk. It does not prescribe a specific visual treatment by itself.

  • safeDefaultRequired is not a styling concern. It is a semantic constraint on interaction policy.

Profile narrowing (per FSL §13.3)

A component-semantics profile may codify a narrower subset of this vocabulary when the broader terms collapse into one of the narrower ones or into another dimension. The @ttoss/ui2 profile codifies three values — neutral, committing, destructive — and rejects the others with explicit rationale:

  • reversible is the logical complement of committing; carrying both doubles the vocabulary without adding an expressible distinction.
  • interruptive is absorbed by the Entity Overlay — an Overlay is interruptive by kind, and non-overlay interruption has no component prototype to justify separate vocabulary.
  • recoverable describes a runtime outcome of failure, not an authorial meta; recovery support belongs in component API (e.g. an onRetry prop), not in ComponentMeta.
  • safeDefaultRequired is a derived policy: destructive already implies the need for a safe default, so codifying the policy separately would create a second source of truth for the same constraint.

The rejections are invariants of the profile, not of FSL — a different profile may legitimately codify more of the vocabulary if its component prototypes create new distinctions.


7. State

State answers:

What interactional or semantic state is active?

State is governed by legality. Not every state is meaningful for every interaction kind.

TermMeaningDistinguish from
defaultThe baseline state in the absence of another active state.Not “normal looking”; it is the unmodified semantic base state.
hoverA pointer-proximity state indicating hover-capable engagement.Not focused; hover is not keyboard focus.
activeA currently engaged action state, often during direct interaction.Not selected or pressed in all cases.
focusedA state indicating current input or interaction focus.Not hover.
disabledA state indicating the entity is unavailable for normal interaction.Not muted; disabled is availability, not emphasis.
selectedA state indicating inclusion or chosen membership in a set.Not always checked; selection and checkedness are related but not identical universally.
pressedA state indicating active pressed engagement, often in command/toggle controls.Not always persistent like selected.
checkedA state indicating affirmative selection or toggle-on condition in applicable interaction kinds.Not selected in every interaction model.
indeterminateA state indicating partial, mixed, or unresolved condition in a tri-state model.Not a visual ambiguity; it is a lawful third semantic state.
expandedA state indicating disclosed or expanded content/structure.Not selected; expansion is visibility structure.
currentA state indicating the current item, location, or active point in a navigational or ordered structure.Not simply selected.
visitedA state indicating prior navigation visitation where such history is semantically meaningful.Not available for all interaction kinds.
droptargetA state indicating that the entity is currently a relevant target for drop-based interaction.Not generic active state.

State law

  • States are not free-form.
  • visited only makes sense where navigation semantics support it.
  • indeterminate only makes sense where tri-state interaction semantics support it.
  • checked is not legal for every entity or interaction.

8. Layer Role

Layer Role answers:

What spatial or hierarchical layer role does this expression occupy?

Layer Role is semantic layering, not raw stack arithmetic.

TermMeaningDistinguish from
baseThe ordinary baseline layer of the interface.Not raised or overlay.
stickyA persistent elevated-presence layer that remains attached to the base interaction context while retaining privileged visibility.Not full overlay behavior.
raisedA higher-emphasis surface or layer relative to the base, without necessarily becoming an overlay.Not the same as overlay.
overlayA layered role above the base interface that creates clear semantic separation.Not necessarily blocking.
blockingA layer role that not only overlays but also semantically blocks or captures interaction from the obscured context.Stronger than overlay.
transientA temporary layer role that appears briefly, lightly, or ephemerally relative to the main interaction structure.Not every overlay is transient, and not every transient layer is blocking.

Critical disambiguations

  • overlay and blocking are not synonyms. Blocking is a stronger condition.

  • raised does not imply modal or layered isolation.


9. Context Class

Context Class answers:

What kind of lawful contextual refinement is in play?

Context does not invent base meaning. It refines what already exists.

TermMeaningDistinguish from
compositionContext arising from semantic placement inside a larger composite structure.Not environment or platform condition.
environmentContext arising from the surrounding operating situation of the interface.Broader than direct interaction mechanics.
interactionEnvironmentContext arising from the conditions of interaction itself, such as device or input modality constraints relevant to interaction behavior.Narrower than general environment.
modeContext arising from a global or local semantic mode of operation.Not simply theme or styling mode.
densityContext arising from semantic compactness or spaciousness of interaction/content arrangement.Not just spacing values; this is contextual interpretation.
accessibilityPreferenceContext arising from explicit accessibility-related user preference or need.Not generic environment.
platformConditionContext arising from platform-specific operating conditions that matter semantically.Not local composition.

Context law

  • Context may refine.
  • Context may not redefine Entity Kind.
  • Context may not collapse distinctions already carried by foundational terms.

10. Critical ambiguity resolutions

This section records the most important foundational distinctions that the lexicon is intended to stabilize.

10.1 Action vs primaryAction

  • Action is an Entity Kind.
  • primaryAction is a Composition Role.

One says what the thing is. The other says what role it plays in a composition.

10.2 Selection vs toggle.binary vs select.single

  • Selection is an Entity Kind.
  • toggle.binary and select.single are Interaction Kinds.

One says what kind of entity it is. The other says how that entity is being interacted with.

10.3 label vs title

  • label identifies an immediate thing.
  • title introduces a larger semantic unit.

10.4 description vs status

  • description explains.
  • status communicates current condition or outcome.

10.5 negative vs destructive

  • negative is Evaluation.
  • destructive is Consequence.

A thing can be negative without being destructive.

10.6 muted vs disabled

  • muted is Evaluation.
  • disabled is State.

A thing can be muted and still interactive. A disabled thing is unavailable for normal interaction.

10.7 overlay vs blocking

  • overlay is Layer Role.
  • blocking is a stronger Layer Role that captures or prevents interaction with the obscured context.

10.8 dismiss vs dismissAction vs closeTrigger

  • dismiss is Interaction Kind.
  • dismissAction is Composition Role.
  • closeTrigger is Structural Role.

These must never be collapsed.


10.9 title vs heading

  • title is a Structural Role — the topological function of a part that introduces its entity or surface.
  • heading is a Composition Role — the relational function of that same part within a larger composite.

A single part may lawfully carry both: structure: title (what it is topologically) and composition: heading (what role it plays in the composition).


10.10 status.interruptive vs interruptive

  • status.interruptive is an Interaction Kind — the mode of semantic operation of a status-communicating entity that operates in an interruptive way.
  • interruptive is a Consequence — the user-facing impact profile of an interaction.

They model different dimensions and may lawfully co-exist. status.interruptive says how the entity operates; interruptive says what impact it has on the user. An expression can carry both simultaneously without redundancy.


10.11 content (Structural Role) — resolved against earlier UX-context overlap

content is a Structural Role (§2): the main carried content of an entity or composite — a topological part descriptor (e.g. the body region of a Disclosure or the inner slot of a Collection).

Historically the Semantic Token Projection also used content as a UX-context family name, which created a verbal overlap across layers. This was resolved by renaming the token-side family to informational — now the canonical name of the UX context covering informational surfaces and readable content. All tokens live under vars.colors.informational.* and the token vocabulary exposes no content key.

Operational rule: content names a Structural Role only. The token UX family is named informational. The two layers no longer share a term.


10.12 Structure (Entity Kind) vs Structural Role (dimension)

  • Structure (capitalized) is an Entity Kind (§1) — an entity whose primary meaning is organizing, supporting, grouping, separating, or framing content and interaction (dividers, layouts, groups).
  • Structural Role is the name of a dimension (§2). Its canonical field in the expression is lowercase structure, and its lexical values are terms like root, control, surface, label, item.

The words are phonetically identical but model different strata. An expression may lawfully carry both simultaneously: entity: Structure, structure: root designates a Structure entity's root part. The Entity Kind is never a legal value of the Structural Role dimension, and no Structural Role term is a legal Entity Kind.

Implementations should preserve the case distinction in every artifact that names both.


10.13 Overlay (Entity Kind) vs overlay (Layer Role)

  • Overlay (capitalized) is an Entity Kind (§1) — an entity whose primary meaning is temporary layered presentation.
  • overlay (lowercase) is a Layer Role (§8) — a semantic layering role occupied by an expression above the base interface.

An Overlay entity typically occupies the overlay or blocking Layer Role, but the two are independent: a non-Overlay entity may lawfully be raised to the overlay layer (e.g. a sticky Navigation), and an Overlay entity's inner parts may occupy different layer roles. The case distinction is normative (see §11.4).


10.14 popup.* (removed from the core) — projection-specific

Earlier drafts of the FSL Interaction Kind vocabulary included popup.listbox, popup.grid, popup.tree, and popup.dialog. These were removed from the core lexicon because they smuggled projection-specific semantics (ARIA composite-widget patterns) into a foundational dimension, violating §3.1 ("Structure must remain smaller than projections") and §12.1 ("No projection-specific term may be treated as foundational").

The meaning those terms carried is recovered at the correct layers:

  • Trigger half — a control that opens a popup expresses interaction: disclose.toggle (reveals/hides related content in place). This is the foundational interaction.
  • Revealed half — the popup's semantic content is modeled as an independent Entity expression: a Collection with listbox/grid/tree-shaped structure, or an Overlay with dialog semantics. The composite relation (trigger ↔ revealed) is expressed through composition and host relations, not a single fused term.
  • ARIA mapping — the concrete pairing between disclose.toggle + revealed Entity and the ARIA role="listbox|grid|tree|dialog" + aria-haspopup attribute lives in the Web/ARIA Projection Profile, where it belongs.

Operational rule: the core Interaction Kind vocabulary contains no popup.* terms. Downstream projection profiles may introduce such pairings as projection-level names, but must not re-inject them into the FSL core.


11. Core disjointness

The following disjointness rules are normative in the core lexicon.

11.1 Entity Kind

All Entity Kinds are pairwise disjoint.

11.2 Evaluation vs State vs Consequence

These dimensions are disjoint by kind of meaning:

  • Evaluation = emphatic/valence meaning
  • State = current condition
  • Consequence = user-facing outcome/risk profile

11.3 Structural Role vs Composition Role

These dimensions serve different semantic purposes and must not be confused.

  • Structural Role = part topology (describes the part itself)
  • Composition Role = relational role in a larger whole (describes where a part belongs)

Slot designator principle: Any Structural Role term may lawfully appear in the Composition dimension as a slot designator — naming the position in a composition reserved for a structurally-typed part. The structural topology provides the naming convention; the dimension provides the semantic distinction. This is not a violation of disjointness.

Example: leadingAdornment in a Structural Role describes a part's topology. The same term in the Composition dimension designates the slot where a leading adornment part belongs in the whole.

11.4 Layer Role vs Entity Kind

A Layer Role must never be used as if it were an Entity Kind.


12. Downstream discipline

The FSL Lexicon is foundational.

Therefore:

  1. No projection-specific term may be treated as foundational just because it is useful downstream.
  2. No token-family term may silently replace a foundational concept.
  3. No component API label may be treated as canonical unless it is grounded in a foundational or approved derived lexicon.
  4. Derived lexicons may extend this one, but may not contradict it.

13. Final statement

This document is the normative dictionary of the FSL core.

It exists so that the system has:

  • a real foundational vocabulary
  • one canonical meaning per core term
  • explicit distinctions between adjacent concepts
  • a stable basis for composition
  • a stable basis for projection
  • a stable basis for deterministic resolution

Its purpose is not to describe implementation.

Its purpose is to ensure that all downstream semantic systems derive from the same language of meaning rather than inventing their own.