# Terezinha Tech Operations (ttoss)
> Trust Terezinha to Simplify and Enhance Your Product Development Process
This file contains all documentation content in a single document following the llmstxt.org standard.
## Agent Context
When working on a project that uses the ttoss ecosystem, AI agents need context about available packages, conventions, and patterns. Without it, agents will reinvent what already exists or violate project conventions.
ttoss provides a ready-made context file at:
```
https://ttoss.dev/ttoss-instructions.txt
```
Fetch and include it in your AI agent's instructions so it understands the ecosystem from the start.
## How to Use It
### GitHub Copilot (`.github/copilot-instructions.md`)
```markdown
Fetch and follow the instructions at https://ttoss.dev/ttoss-instructions.txt.
```
### Cursor (`.cursor/rules` or `.cursorrules`)
```
Fetch and follow the instructions at https://ttoss.dev/ttoss-instructions.txt.
```
### Claude Projects
In the **Project Instructions** field, add:
```
Fetch and follow the instructions at https://ttoss.dev/ttoss-instructions.txt.
```
### Any other AI agent
Add the following line to whatever instructions file or system prompt your tool uses:
```
Fetch and follow the instructions at https://ttoss.dev/ttoss-instructions.txt.
```
## What It Contains
The file gives agents:
- Links to full documentation (`https://ttoss.dev/llms.txt`) and Storybook (`https://storybook.ttoss.dev/llms.txt`)
- Where to report bugs or propose new packages
---
## Agentic Design Patterns
While [Agentic Development Principles](/docs/ai/agentic-development-principles) define the immutable laws of physics and economics for AI integration, and [Agentic Engineering Foundations](/docs/ai/agentic-engineering-foundations) define what must be true of the team and codebase, this page defines the reusable engineering patterns required to build within those constraints.
These are not theoretical concepts; they are reusable design patterns. They provide specific solutions to the recurring problems of cost, latency, reliability, and risk that every agentic system encounters. Use these patterns to bridge the gap between abstract principles and production code.
A pattern differs from a principle and from a corollary: a principle is a truth (it survives being prefixed with "It is true that…"), a corollary is a constraint entailed by a principle (you cannot accept the principle and reject it), and a pattern is one chosen solution among alternatives (it survives "You should…", and a competent team could satisfy the same constraint differently). See [Principles, Corollaries, and Design Patterns](/docs/ai/agentic-development-principles#principles-corollaries-and-design-patterns) for the full distinction. Every pattern below cites the principle it serves; none of them is the only valid way to serve it.
## Table of Contents
```ts
// Carlin adds these parameters automatically
Parameters: {
LambdaS3Bucket: { Type: 'String' },
LambdaS3Key: { Type: 'String' },
LambdaS3ObjectVersion: { Type: 'String' },
}
```
```yml
# Carlin adds these parameters automatically
Parameters:
LambdaS3Bucket:
Type: String
LambdaS3Key:
Type: String
LambdaS3ObjectVersion:
Type: String
```
### Lambda Resource Configuration
Reference the S3 parameters in your Lambda resources. If `Code` or `CodeUri` properties are undefined, Carlin sets them automatically:
```ts
Resources: {
MyLambda: {
Type: 'AWS::Lambda::Function',
Properties: {
Handler: 'auth/index.validateUser',
Code: {
S3Bucket: { Ref: 'LambdaS3Bucket' },
S3Key: { Ref: 'LambdaS3Key' },
S3ObjectVersion: { Ref: 'LambdaS3ObjectVersion' },
},
},
},
MyServerlessFunction: {
Type: 'AWS::Serverless::Function',
Properties: {
Handler: 'users/create.handler',
CodeUri: {
Bucket: { Ref: 'LambdaS3Bucket' },
Key: { Ref: 'LambdaS3Key' },
Version: { Ref: 'LambdaS3ObjectVersion' },
},
},
},
}
```
```yml
Resources:
MyLambda:
Type: AWS::Lambda::Function
Properties:
Handler: auth/index.validateUser
Code:
S3Bucket: !Ref LambdaS3Bucket
S3Key: !Ref LambdaS3Key
S3ObjectVersion: !Ref LambdaS3ObjectVersion
MyServerlessFunction:
Type: AWS::Serverless::Function
Properties:
Handler: users/create.handler
CodeUri:
Bucket: !Ref LambdaS3Bucket
Key: !Ref LambdaS3Key
Version: !Ref LambdaS3ObjectVersion
```
### Lambda Build Process
```mermaid
flowchart TD
A[Analyze CloudFormation template] --> B{Lambda functions found?}
B -->|No| C[Deploy without Lambda build]
B -->|Yes| D[Extract Handler properties]
D --> E[Build Lambda code bundle]
E --> F[Upload to S3 bucket]
F --> G[Inject S3 parameters]
G --> H[Deploy CloudFormation stack]
```
### Format Configuration
Carlin builds Lambda entry points with esbuild, uploads the bundle to S3, and passes the generated S3 object parameters into the CloudFormation stack. Configure output format with `--lambda-format`. Default is `esm`; use `cjs` when a dependency requires CommonJS.
### Runtime Configuration
You can specify the Node.js runtime version for Lambda functions using `--lambda-runtime`. Default is `nodejs24.x`.
Supported runtimes:
- `nodejs20.x` - Node.js 20
- `nodejs22.x` - Node.js 22
- `nodejs24.x` - Node.js 24 (default)
Example:
```bash
carlin deploy --lambda-runtime nodejs20.x
```
This option affects:
- Lambda function runtime version
- Lambda Layer compatible runtimes
- CodeBuild runtime for Lambda Layer builder
## Deploy Report
```bash
carlin deploy report --channel=github-pr
```
After all packages in a monorepo are deployed, `deploy report` collects every `.carlin/*.json` output file across the workspace and publishes a consolidated summary. Use `--channel` to control where the summary is sent.
### `--channel=github-pr`
Posts (or updates) a single PR comment containing a table of all deploy outputs from every package deployed during the CI run. Carlin identifies the PR from the current branch, finds any existing comment it previously posted, and patches it in place — so the comment never duplicates across pushes.
```mermaid
flowchart TD
A[collect all .carlin/*.json files] --> B[build markdown table]
B --> C{PR comment exists?}
C -->|yes| D[PATCH existing comment]
C -->|no| E[POST new comment]
```
The comment looks like this:
| Package | Stack | Output Key | Output Value |
| ----------- | ---------------- | ------------ | ------------ |
| `@acme/api` | `acme-api-pr-42` | `ApiUrl` | https://... |
| `@acme/web` | `acme-web-pr-42` | `BucketName` | acme-web-... |
#### Required environment variables
| Variable | Description |
| ------------------- | ------------------------------------------------------------------------ |
| `GH_TOKEN` | GitHub token with `pull-requests: write` permission. |
| `GITHUB_REPOSITORY` | Repository in `owner/repo` format (set automatically by GitHub Actions). |
| `CARLIN_BRANCH` | The branch being built (used to look up the open PR). |
#### Usage in CI
In the ttoss monorepo this command runs at the end of the PR pipeline, after all packages are deployed:
```bash
# Deploy all packages changed since main
pnpm turbo run build test deploy --filter=[main]
# Build carlin explicitly so the CLI is available even when no packages changed
pnpm turbo run build --filter=carlin
# Post or update a single PR comment with consolidated deploy outputs
pnpm carlin deploy report --channel=github-pr
```
Because Carlin uses `GITHUB_PR_COMMENT_MARKER` as an HTML comment inside the body, it identifies its own comment reliably across multiple pushes to the same PR without creating duplicates.
## Destroy
To destroy the stack, pass `--destroy` to the deploy command:
```
carlin deploy --destroy
```
:::danger
This operation is irreversible. You must pay attention because you may destroy resources that contains your App data, like DynamoDB, using this command.
To reduce accidental deletion, destroy only deletes resources when termination protection is disabled and `--environment` is not defined.
:::
## Examples
```bash
carlin deploy -t src/cloudformation.template1.yml
carlin deploy -e Production
carlin deploy --lambda-runtime nodejs20.x
carlin deploy --lambda-format cjs
carlin deploy --destroy --stack-name StackToBeDeleted
```
### Use Cases
- [POC - AWS Serverless REST API](https://github.com/ttoss/poc-aws-serverless-rest-api/tree/112df23a823294a8b29d0c70f1d0127373759ef1)
## Outputs
After deployment, outputs are saved to `.carlin/$STACK_NAME.json` and `.carlin/latest-deploy.json`.
## API
### Options
| Option | Description |
| -------------------------------- | ------------------------------------------------------------ |
| `--template-path`, `-t` | Path to the CloudFormation template. |
| `--stack-name` | Explicit CloudFormation stack name. |
| `--parameters`, `-p` | CloudFormation parameters as an object or parameter array. |
| `--destroy` | Destroy the selected stack. |
| `--lambda-format` | Lambda bundle format: `esm` or `cjs`. |
| `--lambda-runtime` | Lambda runtime: `nodejs20.x`, `nodejs22.x`, or `nodejs24.x`. |
| `--lambda-external` | Modules excluded from the Lambda bundle. |
| `--lambda-entry-points-base-dir` | Base directory for Lambda handler entry points. |
| `--skip-deploy` | Skip deployment after config resolution. |
| `--channel` | Report deploy outputs to a channel. Supported: `github-pr`. |
`--parameters` accepts a simple object:
```json
{ "DomainName": "api.example.com", "DatabasePort": 5432 }
```
It also accepts CloudFormation-style parameter entries when you need fields such as `usePreviousValue`:
```json
[{ "key": "DatabasePassword", "usePreviousValue": true }]
```
---
## generate-env
Reads a `.env.` file and writes `.env`, optionally merging in CloudFormation outputs from other deployed packages.
## Usage
```bash
carlin generate-env
```
By default this reads `.env.Staging` and writes `.env`. The environment is resolved from the `--environment` flag, falling back to `--default-environment` (default: `Staging`).
## Options
| Option | Alias | Default | Description |
| ----------------------- | ----- | --------- | --------------------------------------------------------------- |
| `--default-environment` | `-d` | `Staging` | Fallback environment name when `--environment` is not set |
| `--path` | `-p` | `./` | Directory where `.env.` source files are looked up |
## Merging Outputs from Other Packages
In a monorepo it is common for one package to need outputs from a stack deployed by another package (e.g. a frontend app needing the AppSync URL from a backend API package). Use `envFromDeployOutputs` in `carlin.yml` to map those outputs into your `.env` file.
```yaml
# carlin.yml
envFromDeployOutputs:
- dir: ../graph-api # relative path to the other package
variables:
VITE_APPSYNC_GRAPHQL_ENDPOINT: AppSyncApiGraphQLUrl.OutputValue
VITE_APPSYNC_CONSOLE_URL: AppSyncApiGraphQLUrl.ExportName
```
Each entry under `envFromDeployOutputs` reads `.carlin/latest-deploy.json` inside `dir` (written by `carlin deploy`). The variable value is a dot-notation path into the outputs object:
- `AppSyncApiGraphQLUrl` — shorthand for `AppSyncApiGraphQLUrl.OutputValue`
- `AppSyncApiGraphQLUrl.OutputValue` — explicit field selection
- `AppSyncApiGraphQLUrl.ExportName` — any other field on the output object
If the file cannot be read, or the specified output key/field does not exist, a warning is logged and that variable is skipped.
Deploy output variables are merged into the generated `.env`. If a key from `envFromDeployOutputs` already exists in `.env.`, the **deploy output value wins** — the static value is removed. This lets you commit a sensible default in `.env.Staging` and have the real deployed value override it automatically.
```bash
# .env.Staging (source)
EXISTING_VAR=from-env-staging-file
VITE_APPSYNC_GRAPHQL_ENDPOINT=https://static-placeholder.example.com/graphql
# .env (generated)
EXISTING_VAR=from-env-staging-file
VITE_APPSYNC_GRAPHQL_ENDPOINT=https://wlzbneunwjctrddgrvlllm.appsync-api.us-east-1.amazonaws.com/graphql
VITE_APPSYNC_CONSOLE_URL=MyStack:AppSyncApiGraphQLUrl
```
## Disabling Deploy Outputs for a Specific Environment
You can set `envFromDeployOutputs: null` under a specific environment in `carlin.yml` to skip deploy output resolution entirely for that environment. This is useful when a particular environment (e.g. `Production`) should always use values baked into the static `.env.Production` file rather than pulling live stack outputs.
```yaml
# carlin.yml
envFromDeployOutputs:
- dir: ../graph-api
variables:
VITE_APPSYNC_GRAPHQL_ENDPOINT: AppSyncApiGraphQLUrl.OutputValue
environments:
Staging:
cloudfront: true
Production:
cloudfront: true
envFromDeployOutputs: null # disables deploy output resolution for Production
```
When `carlin generate-env --environment Production` runs, it reads `.env.Production` as normal but does **not** attempt to read any `latest-deploy.json` files. The generated `.env` contains only the static values from `.env.Production`.
---
## Base Stack
The base stack provides shared infrastructure resources used across multiple carlin deployments. It creates auxiliary resources that enable Lambda deployments, static app hosting, and CI/CD pipelines.
## What is the Base Stack?
The base stack is a CloudFormation stack containing:
- **S3 Bucket**: Stores Lambda code bundles and large CloudFormation templates
- **CloudFront Function**: Appends `index.html` to requests for static websites
- **Lambda Layer Builder**: CodeBuild project for creating Lambda layers
- **Lambda Image Builder**: CodeBuild project for building Docker-based Lambda images
- **VPC**: Network infrastructure for CI/CD Fargate operations
## When to Deploy Base Stack
Deploy the base stack **before** deploying resources that require:
- **Lambda Functions**: Uploads Lambda code to base stack S3 bucket
- **Large CloudFormation Templates**: Templates > 51,200 bytes must be stored in S3
- **Static Websites**: Uses CloudFront function for URL rewriting
- **Docker-based Lambdas**: Builds and stores container images
- **Lambda Layers**: Creates optimized layers from external dependencies
- **CI/CD Pipelines**: Requires VPC for Fargate task execution
## Deploying the Base Stack
Deploy once per AWS region:
```bash
carlin deploy base-stack
```
### Base Stack Naming
The base stack uses a fixed name: `CarlinBaseStack`
This ensures all deployments in the same account and region share the same base resources.
:::note
The base stack does not support `--environment` — there is only one base stack per account/region.
:::
## Base Stack Resources
### S3 Bucket
Stores Lambda code and CloudFormation templates.
**Use cases**:
- Lambda function code bundles (`.zip` files)
- CloudFormation templates exceeding size limits
- Static website builds (temporary storage before CloudFront deployment)
The bucket name is auto-generated by CloudFormation (no custom `BucketName` is specified). The bucket has versioning enabled and a `DeletionPolicy` of `Retain`.
### CloudFront Function
Rewrites URLs to append `index.html` for static websites.
**Behavior**:
- Request: `/docs/guide` → Response: `/docs/guide/index.html`
- Request: `/about` → Response: `/about/index.html`
**Use case**: Deploy Docusaurus, VitePress, or static site generators with clean URLs.
**Example**:
```bash
carlin deploy static-app --append-index-html
# Uses CloudFront function from base stack
```
Every static app in the account associates this same function by ARN, so a
change to it changes all of them at once. Options that alter this behavior for a
single app — such as [`--redirect-to-trailing-slash`](/docs/carlin/commands/deploy-static-app#--redirect-to-trailing-slash)
— deploy a CloudFront function of their own instead.
### Lambda Layer Builder
CodeBuild project for creating Lambda layers from `package.json` dependencies.
**Use case**: Optimize Lambda cold starts by extracting dependencies into layers.
**Example**:
```bash
carlin deploy --lambda-externals aws-sdk,@aws-sdk/client-s3
# Triggers base stack CodeBuild to create layer with specified packages
```
### Lambda Image Builder
CodeBuild project for building Docker images for Lambda functions.
**Use case**: Deploy Lambda functions with custom runtimes or large dependencies (> 250 MB).
**Example**:
```bash
carlin deploy --lambda-dockerfile Dockerfile
# Builds Docker image using base stack CodeBuild
# Pushes to ECR and updates Lambda function
```
### VPC (Virtual Private Cloud)
Network infrastructure for CI/CD Fargate tasks.
**Resources**:
- 3 public subnets (one per availability zone) with `MapPublicIpOnLaunch` enabled
- Internet gateway for outbound connectivity
- Route tables for public routing
**Use case**: Run CI/CD deployments in isolated network environment.
**Example**:
```bash
carlin deploy cicd
# Creates Fargate tasks in base stack VPC
```
## Base Stack Architecture
```mermaid
flowchart TD
A[carlin deploy] --> B{Needs base stack?}
B -->|Lambda deployment| C[S3 Bucket]
B -->|Large template| C
B -->|Static app| D[CloudFront Function]
B -->|Docker Lambda| E[Lambda Image Builder]
B -->|External packages| F[Lambda Layer Builder]
B -->|CI/CD pipeline| G[VPC + Subnets]
C --> H[Upload code/template]
D --> I[Append index.html]
E --> J[Build Docker image]
F --> K[Create Lambda layer]
G --> L[Run Fargate tasks]
H --> M[Deploy to CloudFormation]
I --> M
J --> M
K --> M
L --> M
```
## Verifying Base Stack
Check if base stack exists:
```bash
aws cloudformation describe-stacks --stack-name CarlinBaseStack
```
List base stack resources:
```bash
aws cloudformation list-stack-resources --stack-name CarlinBaseStack
```
## Multi-Region Base Stacks
Deploy base stack to each AWS region you use:
```bash
# US East
AWS_REGION=us-east-1 carlin deploy base-stack
# Europe
AWS_REGION=eu-west-1 carlin deploy base-stack
```
Each region gets an independent `CarlinBaseStack` with region-specific resources.
:::tip
Base stack has termination protection enabled by default to prevent accidental deletion of shared infrastructure.
:::
## Updating the Base Stack
Update base stack when upgrading carlin versions:
```bash
carlin deploy base-stack
```
carlin updates the stack with new resource configurations and features.
## Deleting the Base Stack
:::danger
Deleting the base stack removes shared infrastructure. Ensure no deployments depend on it.
:::
Disable termination protection first:
```bash
aws cloudformation update-termination-protection \
--stack-name CarlinBaseStack \
--no-enable-termination-protection
```
Delete the stack:
```bash
aws cloudformation delete-stack --stack-name carlin-base-stack-us-east-1
```
## Cost Considerations
Base stack resources incur AWS charges:
- **S3 Bucket**: Pay for storage (typically minimal for Lambda code)
- **CloudFront Function**: Free tier available, then pay per request
- **CodeBuild**: Pay per build minute (only when building images/layers)
- **VPC**: VPC itself is free; data transfer costs may apply
- **ECR**: Pay for Docker image storage
Estimated cost: **$5-20/month** depending on usage.
## Troubleshooting
### Base Stack Not Found
**Error**: `Base stack not found: carlin-base-stack-us-east-1`
**Solution**: Deploy the base stack:
```bash
carlin deploy base-stack
```
### Lambda Upload Fails
**Error**: `Cannot upload Lambda code to S3`
**Solution**: Verify base stack bucket exists:
```bash
aws s3 ls | grep carlin-base-stack
```
If missing, redeploy base stack:
```bash
carlin deploy base-stack
```
### Wrong Region Base Stack
**Error**: Deployment uses base stack from different region
**Solution**: Ensure base stack exists in deployment region:
```bash
carlin deploy base-stack --region eu-west-1
carlin deploy --region eu-west-1
```
### Permission Errors
**Error**: `Access denied when accessing base stack resources`
**Solution**: Verify IAM permissions for:
- `s3:PutObject`, `s3:GetObject` on base stack bucket
- `cloudformation:DescribeStacks` on base stack
- `codebuild:StartBuild` for image/layer builders
## Best Practices
### 1. Deploy Base Stack First
```bash
# Setup sequence
carlin deploy base-stack --environment production
carlin deploy --environment production
```
### 2. One Base Stack Per Region-Environment
```bash
# Production US
carlin deploy base-stack --environment production --region us-east-1
# Production EU
carlin deploy base-stack --environment production --region eu-west-1
# Staging US
carlin deploy base-stack --environment staging --region us-east-1
```
### 3. Document Base Stack Dependencies
Add to `README.md`:
````markdown
## Prerequisites
Deploy base stack before first deployment:
```bash
carlin deploy base-stack --environment production
```
````
```
### 4. Monitor Base Stack Costs
Set up AWS Cost Explorer alerts for base stack resources to track unexpected charges.
## Related Topics
- [Deploy](/docs/carlin/commands/deploy) - Deploying stacks that use the base stack
```
---
## CloudFormation Driven Development
CloudFormation Driven Development (CFNDD) is a methodology for building and maintaining cloud applications by thinking infrastructure-first, using [AWS CloudFormation](https://aws.amazon.com/cloudformation/) templates as the foundation for all features and deployments.
## Philosophy
Instead of manually creating AWS resources through the console or CLI, CFNDD advocates:
1. **Template-First Design**: Every feature begins as a CloudFormation template
2. **Infrastructure as Code**: All resources are version-controlled and reproducible
3. **Declarative Architecture**: Define the desired state; AWS handles the how
4. **Automated Deployment**: Use tools like carlin to deploy templates consistently
## Core Principles
### 1. Think in Templates
When building a new feature, ask:
- "What AWS resources does this need?"
- "How would I define this in CloudFormation?"
- "Can I reuse existing resource patterns?"
**Traditional Approach:**
```plaintext
1. Create Lambda via console
2. Set up API Gateway manually
3. Configure IAM roles by clicking
4. Hope you remember for next environment
```
**CFNDD Approach:**
```yaml
Resources:
ApiFunction:
Type: AWS::Serverless::Function
Properties:
Handler: index.handler
Events:
ApiEvent:
Type: Api
Properties:
Path: /users
Method: GET
```
### 2. Version Control Everything
All CloudFormation templates live in your repository:
```plaintext
project/
├── src/
│ └── lambdas/
│ └── api/
│ └── handler.ts
├── cloudformation/
│ └── template.yml # Infrastructure definition
├── carlin.yml # Deployment config
└── package.json
```
**Benefits:**
- Track infrastructure changes over time
- Review infrastructure in pull requests
- Roll back to previous versions
- Share knowledge across team
### 3. Repeatability and Consistency
Deploy the same template to multiple environments:
```bash
# Staging
ENVIRONMENT=staging carlin deploy
# Production
ENVIRONMENT=production carlin deploy
```
**Same template, different contexts:**
- Stack names: `my-app-staging`, `my-app-production`
- Resource names: `my-app-staging-function`, `my-app-production-function`
- Parameters: Different values per environment
### 4. Automation Over Manual Steps
Eliminate click-ops:
| Manual Process | CFNDD Automation |
| ----------------------------- | ---------------------------- |
| Console → Lambda → Create | `carlin deploy` |
| Console → S3 → Create Bucket | CloudFormation resource |
| Console → IAM → Attach Policy | Template `Policies` property |
| Remember what you did | Git history |
## AWS Well-Architected Alignment
CFNDD directly supports the [AWS Well-Architected Framework](https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html) pillars:
| Pillar | CFNDD Benefit |
| -------------------------- | ---------------------------------------------------------------------------------------------- |
| **Operational Excellence** | Infrastructure as code enables change tracking, automated deployments, and rollback capability |
| **Security** | Consistent IAM policies, encryption settings, and network configurations across environments |
| **Reliability** | Reproducible deployments reduce human error; disaster recovery via template redeployment |
| **Performance Efficiency** | Parameterized templates allow right-sizing resources per environment |
| **Cost Optimization** | Version-controlled resources prevent orphaned infrastructure; easy teardown of unused stacks |
## CFNDD with carlin
carlin embodies CFNDD by:
- Supporting custom [CloudFormation templates](/docs/carlin/core-concepts/cloudformation-templates) (TypeScript, YAML, JSON)
- [Auto-detecting Lambda functions](/docs/carlin/core-concepts/cloudformation-templates#lambda-function-handling) from templates and building code with esbuild
- Managing stack lifecycle (create, update, delete)
- Enforcing [naming conventions](/docs/carlin/core-concepts/stack-naming) and best practices
**Example Workflow:**
```bash
# 1. Define your CloudFormation template with a Lambda function
# src/cloudformation.ts
# 2. Deploy (carlin auto-detects Lambda, builds code, uploads to S3, deploys stack)
carlin deploy
```
See [CloudFormation Templates](/docs/carlin/core-concepts/cloudformation-templates) for details on template discovery and Lambda handling.
## Common Patterns
For template examples, see:
- [CloudFormation Templates](/docs/carlin/core-concepts/cloudformation-templates) — Template format, Lambda handling, and TypeScript benefits
- [Deploy](/docs/carlin/commands/deploy) — Deployment options and stack lifecycle
- [Deploy Static App](/docs/carlin/commands/deploy-static-app) — Static website deployment with CloudFront
## Best Practices
1. **Small, focused templates**: One stack per application component
2. **Use TypeScript templates**: Get type safety and reusable helper functions
3. **Export outputs**: Make ARNs/URLs available to other stacks via [`generate-env`](/docs/carlin/commands/generate-env)
4. **Review change sets**: Preview updates before applying
5. **Tag everything**: Include `Environment`, `Application`, `ManagedBy`
6. **Enable termination protection**: Protect production stacks
## Challenges and Solutions
| Challenge | Solution |
| ----------------------------------- | ----------------------------------------------------- |
| Steep learning curve | Start with carlin-generated templates; study AWS docs |
| Template size limits (51,200 bytes) | Use nested stacks or split into multiple stacks |
| Complex intrinsic functions | Use helper scripts or tools like `cfn-lint` |
| Slow stack updates | Parallelize independent stacks; use `AWS::NoValue` |
| Drift detection | Regularly run `aws cloudformation detect-stack-drift` |
## CFNDD vs Other IaC Tools
| Tool | Pros | Cons |
| ------------------ | ---------------------------------------- | ------------------------------------ |
| **CloudFormation** | Native AWS; free; broad resource support | Verbose YAML; slower updates |
| **Terraform** | Multi-cloud; HCL syntax; faster | State management complexity; cost |
| **CDK** | Type-safe; familiar languages | Synthesizes to CloudFormation anyway |
| **Pulumi** | Real programming languages | Smaller community; state management |
**carlin's stance:** Use CloudFormation as the deployment engine, but abstract complexity where possible (auto-generation, conventions).
## Related
- [CloudFormation Templates](/docs/carlin/core-concepts/cloudformation-templates)
- [Stack Naming](/docs/carlin/core-concepts/stack-naming)
- [Base Stack](/docs/carlin/core-concepts/base-stack)
- [AWS CloudFormation Best Practices](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/best-practices.html)
---
## CloudFormation Templates
carlin uses CloudFormation templates to define AWS infrastructure. Templates can be written in TypeScript, YAML, or JSON, giving you flexibility in how you define resources.
## Template Formats
### TypeScript Templates (Recommended)
TypeScript templates provide type safety, IDE autocomplete, and dynamic generation:
```typescript
// cloudformation.ts
export const template = {
Resources: {
MyBucket: {
Type: 'AWS::S3::Bucket',
Properties: {
BucketName: 'my-app-bucket',
VersioningConfiguration: {
Status: 'Enabled',
},
},
},
MyTable: {
Type: 'AWS::DynamoDB::Table',
Properties: {
TableName: 'my-app-table',
BillingMode: 'PAY_PER_REQUEST',
AttributeDefinitions: [{ AttributeName: 'id', AttributeType: 'S' }],
KeySchema: [{ AttributeName: 'id', KeyType: 'HASH' }],
},
},
},
Outputs: {
BucketName: {
Value: { Ref: 'MyBucket' },
Export: { Name: 'MyAppBucketName' },
},
TableName: {
Value: { Ref: 'MyTable' },
},
},
};
```
### YAML Templates
Standard CloudFormation YAML syntax:
```yaml
# cloudformation.yml
Resources:
MyBucket:
Type: AWS::S3::Bucket
Properties:
BucketName: my-app-bucket
VersioningConfiguration:
Status: Enabled
Outputs:
BucketName:
Value: !Ref MyBucket
Export:
Name: MyAppBucketName
```
### JSON Templates
Standard CloudFormation JSON syntax:
```json
{
"Resources": {
"MyBucket": {
"Type": "AWS::S3::Bucket",
"Properties": {
"BucketName": "my-app-bucket"
}
}
},
"Outputs": {
"BucketName": {
"Value": { "Ref": "MyBucket" }
}
}
}
```
## Template Discovery
carlin automatically searches for templates in this order:
1. `./src/cloudformation.ts`
2. `./src/cloudformation.js`
3. `./src/cloudformation.yaml`
4. `./src/cloudformation.yml`
5. `./src/cloudformation.json`
Override with `--template-path`:
```bash
carlin deploy --template-path infrastructure/stack.ts
```
## TypeScript Template Benefits
### 1. Type Safety
```typescript
export const template: CloudFormationTemplate = {
Resources: {
Bucket: {
Type: 'AWS::S3::Bucket',
Properties: {
// TypeScript validates property names
BucketName: 'my-bucket',
// Error: 'InvalidProperty' doesn't exist
// InvalidProperty: 'value',
},
},
},
};
```
### 2. Dynamic Generation
```typescript
const environments = ['dev', 'staging', 'prod'];
export const template = {
Resources: environments.reduce(
(acc, env) => ({
...acc,
[`${env}Bucket`]: {
Type: 'AWS::S3::Bucket',
Properties: {
BucketName: `my-app-${env}-bucket`,
},
},
}),
{}
),
};
```
### 3. Code Reusability
```typescript
// utils/resources.ts
export const createBucket = (name: string) => ({
Type: 'AWS::S3::Bucket',
Properties: {
BucketName: name,
VersioningConfiguration: { Status: 'Enabled' },
PublicAccessBlockConfiguration: {
BlockPublicAcls: true,
BlockPublicPolicy: true,
IgnorePublicAcls: true,
RestrictPublicBuckets: true,
},
},
});
// cloudformation.ts
export const template = {
Resources: {
AssetsBucket: createBucket('my-app-assets'),
BackupsBucket: createBucket('my-app-backups'),
},
};
```
### 4. Environment Variables
```typescript
export const template = {
Parameters: {
Environment: {
Type: 'String',
Default: process.env.NODE_ENV || 'development',
},
},
Resources: {
Database: {
Type: 'AWS::RDS::DBInstance',
Properties: {
DBInstanceClass:
process.env.NODE_ENV === 'production' ? 'db.r5.large' : 'db.t3.micro',
},
},
},
};
```
## Template Structure
Templates follow the standard [AWS CloudFormation template structure](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-anatomy.html) with `Parameters`, `Resources`, `Outputs`, and `Conditions` sections.
Pass parameters during deployment:
```bash
carlin deploy --parameters '{"DomainName":"example.com","InstanceType":"t3.small"}'
```
## Lambda Function Handling
carlin automatically builds and deploys Lambda functions when detected in templates.
### Auto-Detected Lambda
```typescript
export const template = {
Resources: {
MyFunction: {
Type: 'AWS::Lambda::Function',
Properties: {
Runtime: 'nodejs20.x',
Handler: 'handler.handler', // Points to src/handler.ts
Code: {
S3Bucket: { Ref: 'LambdaS3Bucket' },
S3Key: { Ref: 'LambdaS3Key' },
S3ObjectVersion: { Ref: 'LambdaS3ObjectVersion' },
},
},
},
},
};
```
Create `src/handler.ts`:
```typescript
export const handler = async (event: any) => {
return {
statusCode: 200,
body: JSON.stringify({ message: 'Hello from Lambda!' }),
};
};
```
carlin automatically:
1. Builds `src/handler.ts` using esbuild
2. Uploads bundle to S3
3. Injects S3 parameters into template
4. Deploys Lambda function
### Custom Lambda Entry Point
```bash
carlin deploy --lambda-entry-points-base-dir functions
```
Template references `functions/handler.ts` instead of `src/handler.ts`.
## Template Size Limits
CloudFormation templates have a 51,200-byte body limit. carlin automatically uploads large templates to S3.
**Automatic handling**:
```mermaid
flowchart TD
A[Parse template] --> B{Template size > 51KB?}
B -->|No| C[Deploy directly with TemplateBody]
B -->|Yes| D[Upload to base stack S3 bucket]
D --> E[Deploy with TemplateURL]
```
No configuration needed—carlin handles this automatically.
## Template Validation
Validate templates before deployment:
```bash
aws cloudformation validate-template --template-body file://cloudformation.yml
```
Or deploy in validation mode:
```bash
carlin deploy --dry-run # (if supported)
```
## Best Practices
### 1. Use Parameters for Environment-Specific Values
```typescript
// ✅ Good
export const template = {
Parameters: {
DomainName: { Type: 'String' },
},
Resources: {
Distribution: {
Properties: {
DomainName: { Ref: 'DomainName' },
},
},
},
};
// ❌ Bad - hardcoded values
export const template = {
Resources: {
Distribution: {
Properties: {
DomainName: 'production.example.com',
},
},
},
};
```
### 2. Export Important Outputs
```typescript
export const template = {
Outputs: {
ApiUrl: {
Value: { 'Fn::GetAtt': ['Api', 'Url'] },
Export: { Name: 'MyApiUrl' }, // Other stacks can import this
},
},
};
```
### 3. Use TypeScript for Complex Logic
```typescript
const regions = ['us-east-1', 'eu-west-1'];
export const template = {
Resources: Object.fromEntries(
regions.map((region) => [
`Bucket${region.replace(/-/g, '')}`,
{
Type: 'AWS::S3::Bucket',
Properties: {
BucketName: `my-app-${region}`,
},
},
])
),
};
```
### 4. Organize Large Templates
```typescript
// infrastructure/buckets.ts
export const buckets = {
AssetsBucket: {
/* ... */
},
BackupsBucket: {
/* ... */
},
};
// infrastructure/databases.ts
export const databases = {
MainTable: {
/* ... */
},
CacheTable: {
/* ... */
},
};
// cloudformation.ts
export const template = {
Resources: {
...buckets,
...databases,
},
};
```
### 5. Add Resource Dependencies
```typescript
export const template = {
Resources: {
Bucket: {
Type: 'AWS::S3::Bucket',
},
BucketPolicy: {
Type: 'AWS::S3::BucketPolicy',
DependsOn: 'Bucket', // Wait for bucket creation
Properties: {
Bucket: { Ref: 'Bucket' },
PolicyDocument: {
/* ... */
},
},
},
},
};
```
## Troubleshooting
### Template Validation Errors
**Error**: `Template format error: ...`
**Solution**: Validate syntax:
```bash
aws cloudformation validate-template --template-body file://cloudformation.yml
```
### Parameters Not Working
**Error**: Parameters not being passed to stack
**Solution**: Ensure correct JSON format:
```bash
carlin deploy --parameters '{"Key":"Value"}'
```
### Resource Creation Failed
**Error**: CloudFormation resource creation failed
**Solution**: Check CloudFormation console for detailed error messages and stack events.
## Related Topics
- [Commands: deploy](/docs/carlin/commands/deploy) - Template deployment options
---
## Configuration
Use `carlin.ts` when deployment values need TypeScript, validation, or secrets from environment variables. The recommended API is `defineConfig` from `carlin/config`.
## Typed Configuration
```typescript
const values = {
Staging: {
domainName: 'api-staging.example.com',
databaseHost: 'staging.cluster.example.com',
},
Production: {
domainName: 'api.example.com',
databaseHost: 'production.cluster.example.com',
},
};
export default defineConfig(({ environment }) => {
const current = values[environment || 'Staging'];
return {
lambdaFormat: 'cjs',
parameters: {
DomainName: current.domainName,
DatabaseHost: current.databaseHost,
DatabaseUsername: requiredEnv({ name: 'DATABASE_USERNAME' }),
DatabasePassword: requiredEnv({ name: 'DATABASE_PASSWORD' }),
},
};
});
```
`defineConfig` keeps autocomplete for Carlin options and validates the resolved config before deploy. It catches invalid `parameters`, missing parameter values, and invalid `environments` shape early. `requiredEnv` fails fast when a required `.env` or CI variable is missing.
## Configuration Flow
```mermaid
flowchart TD
A[.env or CI variables] --> B[process.env]
C[--environment or CARLIN_ENVIRONMENT] --> D[defineConfig context]
B --> E[carlin.ts]
D --> E
E --> F[Carlin parameters]
G[src/cloudformation.ts Parameters] --> H[carlin deploy]
F --> H
H --> I[CloudFormation stack parameters]
I --> J[Template resources use Ref]
```
Carlin loads dotenv automatically. When an environment is resolved (`--environment`, `--env`, `-e`, `CARLIN_ENVIRONMENT`, or `ENVIRONMENT`), Carlin first loads `.env.` and falls back to `.env` only when that file does not exist. Without a resolved environment, Carlin loads `.env`. CI variables remain available through `process.env`, and the resolved environment is passed to `defineConfig` function configs.
The object returned by `carlin.ts` becomes the CLI config. During `carlin deploy`, `parameters` are converted into CloudFormation stack parameters. Prefer the object form for ordinary values:
```typescript
parameters: {
DomainName: 'api.example.com',
DatabasePort: 5432,
}
```
Use the array form only when you need CloudFormation-specific fields such as `usePreviousValue`:
```typescript
parameters: [
{
key: 'DatabasePassword',
usePreviousValue: true,
},
];
```
Your template declares the same parameter names and uses `Ref` where resources need the values:
```typescript
export default {
Parameters: {
DomainName: { Type: 'String' },
DatabasePassword: { Type: 'String', NoEcho: true },
},
Resources: {
Function: {
Type: 'AWS::Lambda::Function',
Properties: {
Environment: {
Variables: {
DOMAIN_NAME: { Ref: 'DomainName' },
DATABASE_PASSWORD: { Ref: 'DatabasePassword' },
},
},
},
},
},
};
```
Secrets should stay in `.env`, CI secret stores, or existing CloudFormation parameter values. When a secret is passed as a CloudFormation parameter, mark the template parameter with `NoEcho: true`.
## Environment Blocks
You can still use `environments` when you prefer declarative inheritance:
```typescript
export default defineConfig({
parameters: {
DatabasePort: 5432,
},
environments: {
Staging: {
parameters: {
DomainName: 'api-staging.example.com',
DatabasePassword: requiredEnv({ name: 'STAGING_DATABASE_PASSWORD' }),
},
},
Production: {
parameters: {
DomainName: 'api.example.com',
DatabasePassword: requiredEnv({ name: 'PRODUCTION_DATABASE_PASSWORD' }),
},
},
},
});
```
For secrets, prefer the function form when each environment has different required variables. It only reads the variables needed for the selected environment.
---
## Environments
Environments in carlin enable multi-stage deployment workflows (development, staging, production) with automatic termination protection and environment-specific configurations.
## Defining Environments
Specify environment using CLI option, environment variable, or config file:
### CLI Option
```bash
carlin deploy --environment production
```
### Environment Variable
```bash
CARLIN_ENVIRONMENT=staging carlin deploy
```
### Config File
Create `carlin.yml`:
```yaml
environment: staging
```
Deploy:
```bash
carlin deploy
```
## Environment Benefits
### 1. Termination Protection
Stacks deployed with `--environment` automatically enable CloudFormation termination protection, preventing accidental deletion:
```bash
carlin deploy --environment production
# Stack created with termination protection enabled
carlin deploy --destroy --environment production
# Error: Cannot delete stack with termination protection
```
To delete protected stacks:
```bash
# Option 1: Remove environment flag and use stack name
carlin deploy --destroy --stack-name my-app-production
# Option 2: Disable protection in AWS Console first
```
### 2. Environment-Specific Naming
Environment name becomes part of the stack name:
```bash
carlin deploy --environment staging
# Stack: my-app-staging
carlin deploy --environment production
# Stack: my-app-production
```
This creates clear separation between environments without manual stack name management.
### 3. Environment-Specific Parameters
Use different CloudFormation parameters per environment:
```bash
# Staging with smaller instance
carlin deploy --environment staging --parameters '{"InstanceType":"t3.micro"}'
# Production with larger instance
carlin deploy --environment production --parameters '{"InstanceType":"t3.large"}'
```
For larger projects, keep these values in a typed `carlin.ts` file. See [Configuration](/docs/carlin/core-concepts/configuration) for the full flow from environment variables to CloudFormation parameters.
### 4. Configuration Inheritance
Create environment-specific config files:
```yaml
# carlin.yml (base configuration)
region: us-east-1
parameters:
DomainName: app.example.com
```
```yaml
# carlin.staging.yml
environment: staging
parameters:
DomainName: staging.app.example.com
InstanceType: t3.micro
```
```yaml
# carlin.production.yml
environment: production
parameters:
DomainName: app.example.com
InstanceType: t3.large
```
Deploy to specific environment:
```bash
carlin deploy --config carlin.staging.yml
carlin deploy --config carlin.production.yml
```
## Common Environment Patterns
### Three-Stage Pipeline
```bash
# 1. Development (feature branches, no environment)
git checkout feature/new-feature
carlin deploy
# Stack: my-app-feature-new-feature
# No termination protection
# 2. Staging (shared pre-production)
carlin deploy --environment staging
# Stack: my-app-staging
# Termination protection enabled
# 3. Production (live environment)
carlin deploy --environment production
# Stack: my-app-production
# Termination protection enabled
```
### Environment-Based AWS Accounts
Use different AWS credentials per environment:
```bash
# Staging (AWS account 111111111111)
AWS_PROFILE=staging carlin deploy --environment staging
# Production (AWS account 222222222222)
AWS_PROFILE=production carlin deploy --environment production
```
### CI/CD Integration
Configure GitHub Actions for automatic environment deployments:
```yaml
# .github/workflows/deploy.yml
name: Deploy
on:
push:
branches:
- main
- staging
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Deploy to Staging
if: github.ref == 'refs/heads/staging'
run: carlin deploy --environment staging
env:
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID_STAGING }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY_STAGING }}
- name: Deploy to Production
if: github.ref == 'refs/heads/main'
run: carlin deploy --environment production
env:
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID_PROD }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY_PROD }}
```
## Environment vs Branch Naming
See [Stack Naming](/docs/carlin/core-concepts/stack-naming) for the full naming algorithm.
Key difference: deploying with `--environment` enables **termination protection** and the environment name takes precedence over the branch name.
## Environment Variables
Use CloudFormation parameters to pass environment-specific values:
```bash
carlin deploy --environment staging --parameters '{"Environment":"staging","DatabaseInstanceType":"db.t3.small"}'
```
## Best Practices
- **Always use `--environment` for shared stages** (staging, production) to enable termination protection
- **Separate AWS accounts for production** when possible
- **Use parameterized values** instead of hardcoding environment-specific settings
- **Document your environment setup** in a README
## Troubleshooting
### Cannot Delete Environment Stack
**Problem**: Deletion fails with "Stack has termination protection enabled"
**Solution**: Use stack name without environment:
```bash
carlin deploy --destroy --stack-name my-app-production
```
### Wrong Environment Deployed
**Problem**: Deployed to production instead of staging
**Solution**: Always explicitly set environment:
```bash
# Instead of relying on defaults
carlin deploy
# Always specify explicitly
carlin deploy --environment staging
```
### Environment Variable Not Working
**Problem**: `CARLIN_ENVIRONMENT` not being recognized
**Solution**: Verify environment variable is exported:
```bash
export CARLIN_ENVIRONMENT=staging
echo $CARLIN_ENVIRONMENT # Should print: staging
carlin deploy
```
## Related Topics
- [Stack Naming](/docs/carlin/core-concepts/stack-naming) - How environments affect stack names
---
## Stack Naming
carlin automatically generates CloudFormation stack names based on your project configuration, branch name, or environment. Understanding stack naming is critical because it determines how deployments are tracked and updated.
## Automatic Stack Naming
When you don't specify `--stack-name`, carlin generates the name using this algorithm:
1. **First part**: Package name from `package.json` (or `Stack-` if not defined)
2. **Second part**: First defined value from:
- `--environment` option
- Git branch name (converted to param-case)
- `undefined` (if neither is available)
### Examples
| Package Name | Environment | Branch | Stack Name |
| ----------------- | ------------ | -------------- | ------------------------ |
| `my-app` | `Production` | `main` | `my-app-Production` |
| `my-app` | - | `feature/auth` | `my-app-feature-auth` |
| `@company/api` | `Staging` | - | `api-Staging` |
| `my-app` | - | `main` | `my-app-main` |
| (no package.json) | `Production` | - | `Stack-96830-Production` |
:::tip
Scoped package names (e.g., `@company/api`) use only the package name without the scope (`api`).
:::
## Custom Stack Names
Override automatic naming with `--stack-name`:
```bash
carlin deploy --stack-name CustomStack
```
This creates or updates a stack named exactly `CustomStack`, regardless of package name, branch, or environment.
### When to Use Custom Names
- **Shared infrastructure**: Base stacks used across multiple projects
- **Legacy stacks**: Migrating from existing CloudFormation stacks
- **Fixed naming requirements**: Compliance or organizational policies
- **Cross-project resources**: VPCs, DNS zones, shared databases
## Branch-Based Deployments
carlin uses Git branch names to enable feature branch deployments:
```bash
# On branch: feature/user-authentication
carlin deploy
# Creates: my-app-feature-user-authentication
# On branch: fix/bug-123
carlin deploy
# Creates: my-app-fix-bug-123
# On branch: main
carlin deploy
# Creates: my-app-main
```
Branch names are automatically converted to param-case (lowercase with hyphens). Non-ASCII characters (e.g. accented letters like `ç`, `ã`) are normalized to their closest ASCII equivalents before the stack name is used.
### Override Branch Detection
Specify a different branch for stack naming:
```bash
carlin deploy --branch custom-branch
```
Or use environment variable:
```bash
CARLIN_BRANCH=custom-branch carlin deploy
```
**Use case**: Delete a deployment for a deleted branch:
```bash
# Branch feature/auth was already deleted but stack still exists
carlin deploy --destroy --branch feature/auth
```
## Environment-Based Naming
Using `--environment` takes precedence over branch names:
```bash
carlin deploy --environment staging
# Creates: my-app-staging (regardless of branch)
carlin deploy --environment production
# Creates: my-app-production (regardless of branch)
```
Environment-based stacks also enable:
- **Termination protection** (automatic for production)
- **Environment-specific configurations**
- **Clearer deployment separation**
## Stack Name Sanitization
Branch names (and other inputs) may contain characters that are not allowed in CloudFormation stack names. carlin automatically sanitizes the generated name to ensure it satisfies the CloudFormation constraint `[a-zA-Z][-a-zA-Z0-9]*`:
1. **Unicode normalization**: Accented characters are decomposed and their diacritical marks are stripped, mapping them to ASCII equivalents (e.g. `configuração` → `configuracao`, `não` → `nao`).
2. **Invalid character replacement**: Any remaining character that is not a letter, digit, or hyphen is replaced with a hyphen.
3. **Hyphen collapsing**: Consecutive hyphens are collapsed into a single hyphen, and leading/trailing hyphens are removed.
4. **Digit-start fix**: If the resulting name starts with a digit, a `Stack-` prefix is added to satisfy the CloudFormation requirement that names begin with a letter.
### Example with non-ASCII branch name
```bash
# On branch: 1356-adicionar-configuração-para-não-adicionar-sufixos
carlin deploy
# Stack name becomes: OneclickadsGraphApi-1356-adicionar-configuracao-para-nao-adicionar-sufixos
```
## Stack Name Constraints
CloudFormation stack names must:
- Be unique per AWS account and region
- Contain only alphanumeric characters and hyphens
- Be 128 characters or less
- Start with an alphabetic character
carlin enforces a **100-character limit** for AppSync API compatibility (AWS AppSync uses stack names for API names).
### Non-ASCII Character Normalization
Branch names containing non-ASCII characters (e.g. accented letters in Portuguese or Spanish) are automatically normalized so the resulting stack name satisfies the CloudFormation `[a-zA-Z][-a-zA-Z0-9]*` constraint:
1. Unicode characters are decomposed using NFKD normalization (e.g. `ç` → `c` + combining cedilla).
2. Combining diacritical marks are removed, leaving the base ASCII letter.
3. Any remaining characters that are not letters, digits, or hyphens are replaced with a hyphen.
4. Consecutive hyphens are collapsed into a single hyphen and leading/trailing hyphens are stripped.
5. If the name would start with a digit after normalization, it is prefixed with `Stack-`.
6. If normalization produces an empty string, `Stack` is used as a fallback.
**Example** (branch names with Portuguese characters):
```bash
# Branch: 1356-adicionar-configuração-para-não-adicionar-os-sufixos
# Package: @oneclickads/graph-api
carlin deploy
# Stack: OneclickadsGraphApi-1356-adicionar-configuracao-para-nao-adicionar-os-sufixos
```
:::caution
Changing the automatically generated stack name creates or updates a different CloudFormation stack. Use `--stack-name` only when you intentionally want to target a specific stack.
:::
## Configuration Priority
Stack name resolution priority (highest to lowest):
1. `--stack-name` CLI option
2. `stackName` in `carlin.yml`
3. `CARLIN_STACK_NAME` environment variable
4. Automatic generation (package + environment/branch)
## Common Patterns
### Multi-Environment Strategy
```bash
# Development (feature branches)
carlin deploy
# Stack: my-app-feature-name
# Staging (shared environment)
carlin deploy --environment staging
# Stack: my-app-staging
# Production (protected environment)
carlin deploy --environment production
# Stack: my-app-production
```
### Monorepo with Multiple Stacks
```json
// package.json
{
"name": "@company/api"
}
```
```bash
# API stack
carlin deploy --environment production
# Stack: api-production
# Different service in same repo
cd ../workers
carlin deploy --environment production
# Stack: workers-production
```
### Fixed Infrastructure Stack
```bash
# VPC shared across all environments
carlin deploy --stack-name company-vpc --template-path infrastructure/vpc.ts
# All projects reference this VPC
```
## Stack Name Algorithm
When `--stack-name` is not provided, carlin builds the stack name from the package name and the selected environment or Git branch. The generated value is sanitized for CloudFormation by removing unsupported characters, normalizing non-ASCII text, collapsing repeated hyphens, and prefixing `Stack-` when the name would otherwise start with a number.
## Troubleshooting
### Stack Name Conflicts
**Problem**: Different branches create the same stack name.
**Solution**: Use explicit stack names or environments:
```bash
carlin deploy --stack-name unique-name
# or
carlin deploy --environment feature-1
```
### Stack Already Exists
**Problem**: Deploying to a branch that already has a stack.
**Solution**: This is expected behavior. carlin updates the existing stack instead of creating a new one.
### Cannot Delete Stack
**Problem**: Stack has termination protection enabled.
**Solution**: Disable termination protection in AWS Console or deploy without `--environment`:
```bash
# This won't work if environment is set
carlin deploy --destroy --environment production
# This works (removes environment constraint)
carlin deploy --destroy --stack-name my-app-production
```
---
## Introduction
**carlin** is a CLI tool for deploying AWS infrastructure using CloudFormation templates. It automates Lambda code building, S3 uploads, stack naming, multi-environment deployments, and CI/CD pipelines.
## What is carlin?
carlin started in 2018 as deployment scripts for managing CloudFormation stacks across multiple environments (development, staging, production). After streamlining numerous deployments, we packaged these scripts into a unified CLI tool.
Today, carlin handles:
- **CloudFormation deployments** with automatic stack naming
- **Lambda functions** with code building and S3 uploads
- **Static websites** via S3 and CloudFront
- **CI/CD pipelines** with GitHub and Slack integration
- **Environment variables** generation from stack outputs
- **Multi-environment** configurations with termination protection
- **Deploy reports** posted to GitHub PR comments via `carlin deploy report`
## Why Use carlin?
### Simplified AWS Deployments
Deploy CloudFormation stacks with a single command:
```bash
carlin deploy
```
carlin automatically:
- Finds your CloudFormation template
- Builds Lambda function code
- Uploads to S3 with versioning
- Creates or updates stacks
- Displays outputs
### Automatic Lambda Handling
No manual Lambda packaging—carlin detects Lambda functions in templates, builds code with esbuild, uploads to S3, and injects parameters automatically.
### Multi-Environment Support
Deploy to multiple environments with built-in protection:
```bash
carlin deploy --environment Staging
carlin deploy --environment Production # includes termination protection
```
This supports the [E6: U-curve Principle](https://ttoss.dev/docs/product/product-development/principles#e6-the-u-curve-principle-important-trade-offs-are-likely-to-have-u-curve-optimizations) by balancing automation with safety controls.
### Branch-Based Deployments
Test feature branches with automatic stack naming:
```bash
# On feature/auth branch
carlin deploy
# Creates: my-app-feature-auth
```
### Infrastructure as TypeScript
Write CloudFormation templates in TypeScript with type safety and dynamic generation:
```typescript
export const template = {
Resources: {
Bucket: {
Type: 'AWS::S3::Bucket',
Properties: {
BucketName: `my-app-${process.env.NODE_ENV}`,
},
},
},
};
```
## Use Cases
- **Serverless APIs** — Deploy Lambda functions with API Gateway via [CloudFormation templates](/docs/carlin/core-concepts/cloudformation-templates)
- **Static Websites** — Deploy React/Vue/Vite apps to S3 + CloudFront via [`deploy static-app`](/docs/carlin/commands/deploy-static-app)
- **Full-Stack Applications** — Combine infrastructure, APIs, and frontends using [`deploy`](/docs/carlin/commands/deploy) and [`generate-env`](/docs/carlin/commands/generate-env)
## Quick Start
Get started in 5 minutes:
1. **Install carlin**:
```bash
pnpm add -D carlin
```
2. **Create CloudFormation template** (`cloudformation.ts`):
```typescript
export const template = {
Resources: {
MyBucket: {
Type: 'AWS::S3::Bucket',
},
},
Outputs: {
BucketName: {
Value: { Ref: 'MyBucket' },
},
},
};
```
3. **Deploy**:
```bash
carlin deploy
```
## Documentation Structure
- **[Core Concepts](/docs/carlin/core-concepts/stack-naming)** - Stack naming, environments, configuration, base stack, templates
- **[Commands](/docs/carlin/commands/deploy)** - Complete command reference
## Key Features
- **[Automatic Stack Naming](/docs/carlin/core-concepts/stack-naming)** — Generates stack names from `package.json` and branch/environment
- **[Typed Configuration](/docs/carlin/core-concepts/configuration)** — Connect `.env`, `carlin.ts`, and CloudFormation parameters with validation
- **[Lambda Code Building](/docs/carlin/commands/deploy#lambda)** — Automatic code bundling with esbuild, S3 upload, and parameter injection
- **[Static App Deployment](/docs/carlin/commands/deploy-static-app)** — One command deploys to S3 + CloudFront
- **[Environment Variables](/docs/carlin/commands/generate-env)** — Generate `.env` files from stack outputs
- **[Multi-Environment Support](/docs/carlin/core-concepts/environments)** — Automatic termination protection for environment-based deployments
## Community and Support
- **GitHub**: [ttoss/ttoss](https://github.com/ttoss/ttoss)
- **Issues**: [Report bugs or request features](https://github.com/ttoss/ttoss/issues)
---
## Enterprise Neutral
:::caution Status: draft — formal style profile, not a shipped theme
This document is a [Formal Style Profile](/docs/design/design-system/design-tokens/theme-authoring#formal-style-profile) for a planned enterprise archetype. The built-in themes that actually ship with `@ttoss/fsl-theme` today are the default `baseTheme` (exported by `createTheme()`) and `bruttal` — see the [package README](https://github.com/ttoss/ttoss/blob/main/packages/fsl-theme/README.md).
:::
## Purpose
Enterprise Neutral is a product-facing archetype for serious, scalable, low-noise interfaces.
It is designed for:
- dashboards
- admin panels
- backoffice tools
- internal products
- operational workflows
- productivity-heavy UI
- enterprise SaaS
It is not designed to maximize novelty, tactility, or visual spectacle.
Its role is to provide a **high-trust, low-distraction, semantically stable** visual posture that works well across dense surfaces, long sessions, and mixed-skill user populations.
## Core archetype principle
Enterprise Neutral is **neutral-led Flat 2.0**.
It preserves the reduced, screen-native, structurally disciplined posture of Flat 2.0, but applies it in a way that prioritizes:
- clarity over atmosphere
- hierarchy over decoration
- consistency over expressiveness
- trust over novelty
- focus over visual drama
The archetype should feel:
- calm
- reliable
- legible
- systematic
- product-grade
- adaptable across brands without losing structural coherence
## Non-goals
Enterprise Neutral must not become:
- visually empty to the point of weak affordance
- highly expressive or brand-dominant
- premium-glossy or materially theatrical
- playful, nostalgic, or tactile by default
- ultra-flat in a way that weakens interaction confidence
- dense in a way that sacrifices scanability
- dependent on one platform’s component aesthetics
## Structural posture
### Visual character
The interface should read as:
- low-ornament
- low-material
- shallow-layered
- neutral-dominant
- contrast-disciplined
- state-explicit
### Interaction character
The interface should feel:
- direct
- predictable
- calm
- non-theatrical
- efficient
- easy to scan
- easy to recover from
### Semantic discipline
This archetype must not introduce any new semantic vocabulary.
It must implement visual posture entirely through:
- core value choices
- semantic mappings
- bounded family constraints
- recipe-level patterns where necessary
Semantic token names remain stable. Core values and mappings may vary. That boundary is non-negotiable.
## Family constraints
Indexed by token family, using the five constraint levels defined by [Theme Authoring](/docs/design/design-system/design-tokens/theme-authoring#formal-style-profile) — read there for what `Required`, `Preferred`, `Discouraged`, and `Forbidden` commit a theme to. This archetype declares no `Tolerated` constraints.
### 1. Colors
**Posture:** neutral-led, role-clear, restrained accent use.
#### Required
- neutrals must dominate the general interface
- primary action color must be clear and stable
- additional hues must be sparse and purposeful
- text, border, and background relationships must stay explicit
- selected/current/focus states must remain clearly distinguishable
#### Preferred
- one primary action hue
- one neutral scale doing most surface and contrast work
- subdued support colors
- restrained brand saturation
- explicit semantic contrast rather than atmospheric color blending
#### Discouraged
- many competing accent hues
- broad colorful surfaces
- ambiguous contrast between static and interactive elements
- monochrome systems where clickability becomes guesswork
#### Forbidden
- color usage that blurs semantic roles
- brand-led color treatment that overpowers structure
- decorative gradients doing the work of hierarchy
### 2. Typography
**Posture:** productive, sober, high-legibility, hierarchy-first.
#### Required
- sans-serif primary family
- strong distinction between body, label, title, and headline roles
- predictable scale progression
- high legibility at standard enterprise densities
- restrained display behavior
#### Preferred
- productive rather than expressive type posture
- compact but readable body text
- moderate heading emphasis
- low-drama letter-spacing and weight variation
#### Discouraged
- editorial drama as the dominant mode
- decorative display styles
- overly compressed or overly airy rhythm
#### Forbidden
- typography carrying interaction meaning by itself
- decorative type styles that reduce scanability
### 3. Spacing
**Posture:** balanced, structured, compact-capable.
#### Required
- strong grouping through spacing
- consistent rhythm across stack, inline, and inset patterns
- enough room to preserve scanability in dense layouts
- separation of interactive targets must remain ergonomic
#### Preferred
- balanced density by default
- compact mode only as a deliberate variant
- surface padding clearly differentiated from control padding
#### Discouraged
- ultra-tight layouts as the default
- very spacious “marketing-style” rhythm in application shells
#### Forbidden
- density that collapses hierarchy
- spacing that makes controls and content visually indistinct
### 4. Sizing
**Posture:** function-first, ergonomic, non-expressive.
#### Required
- interaction targets must remain clearly usable
- visual size and hit size must remain distinct where needed
- full-height layouts should feel stable and utilitarian
- measures and max-widths should prioritize readability and operational clarity
#### Preferred
- moderate icon sizes
- moderate identity sizing
- strong consistency in hit target behavior
#### Discouraged
- overly small visual affordances
- oversized hero-scale interface primitives in core product views
#### Forbidden
- visually reduced controls with undersized interactive geometry
### 5. Radii
**Posture:** restrained to moderate.
#### Required
- controls and surfaces must feel coherent
- rounding must not dominate visual identity
- corners should support a sense of calm modernity without softness drift
#### Preferred
- moderate control radius
- moderate-to-slightly-larger surface radius
- full rounding only for explicitly pill or circular forms
#### Discouraged
- high curvature as a general language
- mixed angular/soft systems without a clear rule
#### Forbidden
- ornamental curvature
- radii expressive enough to make the archetype feel playful or decorative
### 6. Borders
**Posture:** visible, structural, non-theatrical.
#### Required
- controls must have reliable boundary clarity
- dividers must support grouping without noise
- selected and focus contracts must remain stronger than resting outlines
- border semantics must remain clearer in dense enterprise surfaces than in consumer-soft UIs
#### Preferred
- subtle but explicit control outlines
- muted surface outlines where needed
- strong focus ring visibility
#### Discouraged
- border removal where depth is too weak to compensate
- “invisible boundary” aesthetics in dense application UI
#### Forbidden
- ghost-state ambiguity
- focus or selected treatments that are too weak to trust
### 7. Elevation
**Posture:** shallow and bounded.
#### Required
- depth must be limited and systematic
- overlays, cards, and modals must differentiate clearly
- flat surfaces must remain the baseline
- the system should use few elevation strata
#### Preferred
- subtle raised surfaces
- stronger overlay/modal depth only when necessary
- depth that supports hierarchy, not mood
#### Discouraged
- decorative shadow richness
- many competing depth levels
- strong ambient softness
#### Forbidden
- realism-heavy shadow systems
- depth as visual spectacle
### 8. Opacity
**Posture:** restricted and functional.
#### Required
- opacity should remain secondary to semantic color and depth
- scrims and loading states must stay clear and predictable
- opacity should not become a general styling trick
#### Preferred
- sparse use
- explicit semantic use only
#### Discouraged
- softened haze across broad UI surfaces
- atmospheric translucency as a general product language
#### Forbidden
- opacity replacing semantic contrast or structural distinction
### 9. Motion
**Posture:** restrained, fast, functional.
#### Required
- motion must support feedback, transition clarity, and continuity
- motion should not become a personality layer
- reduced-motion support must remain first-class
#### Preferred
- fast feedback
- short transitions
- calm entry/exit behavior
- little or no decorative motion
#### Discouraged
- bouncy, playful, or cinematic movement
- emphasis motion used too often
#### Forbidden
- motion as a substitute for hierarchy or signifiers
- decorative animation loops in core workflows
### 10. Z-Index
**Posture:** structural and conservative.
#### Required
- layering order must remain obvious
- modal and overlay hierarchies must feel stable
- no arbitrary escalation culture
#### Preferred
- few clear strata
- predictable overlay behavior
#### Discouraged
- many competing floating layers
#### Forbidden
- ad hoc layer inflation
### 11. Breakpoints
**Posture:** infrastructure-only, content-first.
#### Required
- responsive logic must preserve operational clarity
- layout changes must follow content stress, not device stereotypes
#### Preferred
- conservative breakpoint set
- container-first component adaptation where possible
#### Discouraged
- too many layout thresholds
- style-driven breakpoint proliferation
#### Forbidden
- breakpoints used as a substitute for local component adaptability
## Cross-family rules
The following cross-family rules are part of the profile:
### Hierarchy rule
Hierarchy must come primarily from:
1. layout structure
2. typography
3. color contrast
4. bounded depth
5. explicit states
Not from:
- ornament
- atmosphere
- material spectacle
### Affordance rule
Controls must remain recognizable through some combination of:
- boundary
- contrast
- label clarity
- grouping
- state differentiation
Flat reduction must never weaken confidence in what is actionable.
### Calmness rule
The interface should feel focused and low-noise, but not under-signified.
### Consistency rule
Any cue reintroduced by Flat 2.0 — depth, shadow, gradient, glow, border strengthening, tonal layer shift — must be systemized. It must not appear as local decoration.
## Mode posture
### Base mode
**Light-first**
This archetype should be authored primarily as a light-first theme.
### Dark mode
Dark mode is supported, but must preserve:
- clear layer separation
- text/background readability
- border visibility
- focus/current/selected distinction
- restrained but still readable depth
Dark mode must not become softer, hazier, or more atmospheric than the light mode by default.
## Recipe expectations
This archetype assumes that some clarity cannot be solved by tokens alone.
Recipe-level expectations include:
- buttons must preserve obvious action signifiers
- links in content must remain recognizable
- cards/panels must use bounded layer logic
- ghost buttons must be used carefully
- selected/current states should often combine line + color, not color alone
- overlays and modals must escalate clearly from base surfaces
## Override model
This archetype should be highly override-friendly in these areas:
- brand action hue
- neutral palette tuning
- typeface choice
- density tuning
- radius softness
- shallow depth character
It should be less flexible in these areas:
- semantic role clarity
- focus visibility
- selected/current distinction
- excessive motion
- excessive elevation
- diffuse color expressiveness
## AI-facing profile summary
If this archetype is exposed to AI systems, its core steering summary should be:
- enterprise
- neutral-led
- calm
- productive
- low-noise
- shallow-layered
- state-explicit
- restrained motion
- moderate radius
- strong semantic clarity
### Allowed moves
- subtle neutral layering
- disciplined accent hue
- moderate radius tuning
- compact/balanced density tuning
- shallow elevation tuning
- restrained premium polish
### Forbidden moves
- ultraflat ambiguity
- playful softness as default
- expressive gradients as a hierarchy system
- atmospheric translucency as core language
- decorative motion
- weak focus/current/selected states
## Implementation intent
This archetype is intended to become:
1. a Formal Style Profile
2. a Built-in Theme
3. a default-grade starting point for product teams
4. a stable base for AI-assisted theme derivation
## Summary
Enterprise Neutral is a **Flat 2.0 product archetype** for serious, scalable software.
It keeps the reduction and clarity of Flat 2.0, but binds them to:
- neutral dominance
- bounded depth
- explicit state clarity
- restrained motion
- disciplined density
- high semantic trust
Its purpose is not to look trendy.
Its purpose is to make real product interfaces feel clear, reliable, modern, and easy to work in for long periods of time.
---
## Built-in Themes
`@ttoss/fsl-theme` ships two themes. `baseTheme` is the default that `createTheme()` extends when no base is given — a light-first theme with a built-in dark alternate. `bruttal` is exported from the same package. Integration and usage live in the [`@ttoss/fsl-theme` README](https://github.com/ttoss/ttoss/blob/main/packages/fsl-theme/README.md).
This section also holds documents that are not shipped code. [Enterprise Neutral](/docs/design/built-in-themes/enterprise-neutral) is a draft **Formal Style Profile** — a design constraint document awaiting implementation, not a shipped theme. The profile format is defined in [Theme Authoring](/docs/design/design-system/design-tokens/theme-authoring).
---
## Component Model
The Component Model is the **Component Semantics Projection** — [layer 3 of the FSL architecture](/docs/design/design-system/fsl/). It derives from the [FSL Lexicon](/docs/design/design-system/fsl/fsl-lexicon) and [FSL Structural Language](/docs/design/design-system/fsl/fsl-structural-language) and must not define vocabulary that contradicts them.
:::info Status: implemented in `@ttoss/fsl-ui`
This document is the design specification for the Component Semantics Projection, now **implemented** by `@ttoss/fsl-ui`: `taxonomy.ts` (vocabulary + legality matrices), `ComponentMeta`, `ENTITY_COMPOSITION` / `ENTITY_STRUCTURE` / `ENTITY_TOKEN_MAPPING` (`packages/fsl-ui/src/tokens/projection.ts`), and contract tests that auto-validate every component against the matrices. The [Semantic Token Projection](/docs/design/design-system/design-tokens/model) (layer 4, `@ttoss/fsl-theme`) is also implemented. The **Resolution contract** (layer 5) is satisfied by distributed mechanisms — see the [FSL overview](/docs/design/design-system/fsl/). Where this document and the shipped code diverge, the code + its contract tests are the source of truth.
:::
The central rule:
> **A component has an immutable identity. An instance carries that identity into a composition.**
## FSL dimension mapping
The model adopts FSL dimension names directly (no projection renames; FSL §17.1 permits renames but this profile keeps the foundation vocabulary):
| FSL dimension | Model name | Notes |
| :--------------- | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Entity Kind | **Entity** | Values identical; field name is `entity` in `ComponentMeta` and all `*Meta` declarations |
| Structural Role | **Structure** | Root structural role of the component (e.g. `root`); legal values constrained per Entity via `ENTITY_STRUCTURE` |
| Composition Role | **Composition** | Flat vocabulary; Lexicon §4 values plus three declared profile extensions (`step`, `summary`, `navigation`). Per-Entity legality via `ENTITY_COMPOSITION` in `taxonomy.ts`. |
| Interaction Kind | — | **Deferred** per FSL §13.3 — not codified in this profile. See `taxonomy.ts` §Dimension Coverage for rationale and readmission criterion. |
| Evaluation | **Evaluation** | Values identical |
| Consequence | **Consequence** | Profile-narrowed subset — `neutral`, `committing`, `destructive` only (`CONSEQUENCES` in `taxonomy.ts`); the remaining [Lexicon §6](/docs/design/design-system/fsl/fsl-lexicon#6-consequence) values are rejected with recorded rationale (see [Consequence](#consequence) below) |
| State | **State** | Values identical; runtime-resolved by React Aria render props, not authorially declared |
| Layer Role | — | **Absorbed** per FSL §13.3 — captured by the token projection's `surfaceType` (`control`/`surface`), the elevation strata (`flat`/`raised`/`overlay`/`blocking`), and the z-index layer scale (`base`/`sticky`/`overlay`/`blocking`/`transient`), which jointly recover all six Lexicon §8 layer roles. See `taxonomy.ts` §Dimension Coverage. |
| Context Class | — | **Deferred** per FSL §13.3 — refinement dimension (density, mode, a11y preferences) with no prototype exercising it. Readmission criterion: a component that dispatches on a context class at runtime — e.g. a density variant that changes which spacing/sizing tokens a component consumes. Mode switching shipped end-to-end in `@ttoss/fsl-theme` without any component-level dispatch, evidence that `mode` lives at the theme layer, not in `ComponentMeta`. See `taxonomy.ts` §Dimension Coverage. |
## Entity → Token UX context mapping
The normative Entity → `ux` context mapping lives in `ENTITY_TOKEN_MAPPING`
in `packages/fsl-ui/src/tokens/projection.ts` — the single source of truth,
enforced by contract tests. The table below mirrors it for reading; on any
divergence, the code wins.
| Entity | Token `ux` context | Notes |
| :------------- | :----------------- | :-------------------------------------------------------------------------------- |
| **Action** | `action` | 1:1 |
| **Input** | `input` | 1:1 |
| **Selection** | `input` | Selection components consume `input.*` tokens; no separate `selection` UX context |
| **Navigation** | `navigation` | 1:1 |
| **Feedback** | `feedback` | 1:1 |
| **Collection** | `informational` | Collection surfaces consume `informational.*` for structural coloring |
| **Overlay** | `informational` | Overlay surfaces consume `informational.*` for surface coloring |
| **Disclosure** | `navigation` | Disclosure triggers colored as `navigation.*` when acting as location anchors |
| **Structure** | `informational` | Structural surfaces consume `informational.*` |
For the full `ux` role and state grammar, see the [Colors family — FSL Entity Kind Mapping](/docs/design/design-system/design-tokens/families/colors#fsl-entity-kind-mapping).
## ComponentExpression
The model is expressed as a `ComponentExpression` — the typed semantic expression that the resolution pipeline consumes:
```ts
type ComponentExpression = {
entity: Entity; // required — what the component IS
structure: StructuralRole; // required — root structural role (e.g. 'root'); legality per Entity via ENTITY_STRUCTURE
composition?: CompositionRole; // optional — flat slot name (FSL Lexicon §4)
evaluation?: Evaluation; // optional — emphatic meaning
consequence?: Consequence; // optional — risk profile
};
```
All dimensions are defined in `taxonomy.ts` and derived from FSL core vocabulary.
> **Code type:** the implementation exposes `ComponentMeta` (`packages/fsl-ui/src/semantics/componentMeta.ts`) — the identity type every component declares (`entity`, `structure`, `composition?`, `consequence?`). `ComponentExpression` above is the projection's conceptual shape; `ComponentMeta` is its shipped runtime surface.
---
## Entity
Entity answers: _What is this component?_
Every component has exactly one Entity. It cannot change based on context, variant, or usage. If a different Entity is required, a different component must exist.
| Entity | Use for | Typical examples |
| :------------- | :-------------------------------------------------- | :------------------------------------ |
| **Action** | triggering actions or commands | button, action button, icon button |
| **Input** | direct user input | text field, text area, search field |
| **Selection** | choosing one or more options | checkbox, radio group, select, picker |
| **Collection** | structured sets of items | menu, list, table, tree, grid |
| **Navigation** | movement across destinations or views | link, breadcrumbs, tabs, nav item |
| **Disclosure** | revealing or hiding related content in place | accordion, disclosure trigger |
| **Overlay** | temporary layered UI above the interface | dialog, popover, tooltip, drawer |
| **Feedback** | communicating state, status, or outcome | alert, banner, toast, progress |
| **Structure** | organizing interface structure and support surfaces | panel, section, shell, frame |
---
## Composition Model
Composition answers: _What slot does this instance occupy inside a larger composite?_
Composition is a **flat vocabulary** per FSL Lexicon §4 and FSL §5.4. A composition role names the slot; legality is per Entity (not per parent component). When omitted, the component resolves tokens from its Entity default. The vocabulary is the Lexicon §4 set **plus three profile extensions** (`step`, `summary`, `navigation` — Structure-only slots), declared per FSL §17's extension model.
Case discipline: the `navigation` slot (lowercase, Composition) is distinct from the `Navigation` Entity Kind — the same convention the Lexicon applies to `Structure`/`structure` (§10.12) and `Overlay`/`overlay` (§10.13). The slot names a position inside a structural composite; the Entity names what a component is.
### Composition roles
The projection codifies 14 composition roles. The table shows each role's meaning and which Entities may carry it (source of truth: `ENTITY_COMPOSITION` in `taxonomy.ts`).
| Role | Meaning | Legal Entities |
| :------------------ | :----------------------------------------------------- | :-------------------------- |
| **primaryAction** | main forward / commit action in a composite | Action |
| **secondaryAction** | subordinate but intentional action | Action |
| **dismissAction** | cancel / close without committing | Action |
| **heading** | compositional heading slot | Overlay, Structure |
| **body** | compositional body slot | Overlay, Structure |
| **status** | compositional status / validation slot | Input, Feedback |
| **control** | primary control-bearing slot | Input, Selection |
| **label** | naming / label slot | Input, Selection, Structure |
| **description** | descriptive / helper-text slot | Input, Selection, Structure |
| **supporting** | supporting child slot (broader than label/description) | Input, Structure |
| **selection** | selection-bearing slot | Selection |
| **step** | step slot (e.g. progression marker) | Structure |
| **summary** | summary slot | Structure |
| **navigation** | navigation slot inside a structural composite | Structure |
### Parent disambiguation
Because the vocabulary is flat, the same role name may appear in multiple composites — for example, a `label` slot exists on both TextField (Input) and a Structure composite. Runtime and CSS disambiguation comes from the rendered DOM, not from adding a `host` level to the data model:
- `data-scope` + `data-part` on the composite container identify the parent (e.g. `data-scope="dialog" data-part="actions"` on `DialogActions`).
- `data-composition` on the slot-bearing child carries the role name.
Example selector: `[data-scope="dialog"][data-part="actions"] [data-composition="primaryAction"]` resolves a dialog's primary action unambiguously, without a `host` level.
---
## Evaluation
Evaluation answers: _What emphatic or evaluative meaning does this expression carry?_
Evaluation is optional. When omitted, each component applies its own documented default — and that is the design: defaults live with the component, because that is where the knowledge lives. Add it explicitly only when the default is wrong.
Legality is per Entity (source of truth: `ENTITY_EVALUATION` in `taxonomy.ts`), same as the Composition table:
| Value | Use for | Legal Entities |
| :------------ | :----------------------------------- | :----------------------------------------------------------------------- |
| **primary** | main intended emphasis | Action, Collection, Overlay, Navigation, Disclosure, Feedback, Structure |
| **secondary** | subordinate but still intentional | Action, Overlay, Navigation |
| **accent** | deliberately differentiated emphasis | Action, Overlay, Navigation, Feedback |
| **muted** | de-emphasized but still meaningful | Action, Collection, Overlay, Navigation, Disclosure, Structure |
| **positive** | affirming, successful, or favorable | Feedback |
| **caution** | warning or careful-attention signal | Feedback |
| **negative** | harmful, erroneous, or adverse | Action, Overlay, Feedback |
`Input` and `Selection` carry **no** evaluations: form controls are data-entry surfaces, not decision hierarchies, and validation is the runtime `invalid` State (`isInvalid`), never `evaluation: 'negative'` — see the design note on `ENTITY_EVALUATION` in `taxonomy.ts`.
---
## Consequence
Consequence answers: _What user-facing consequence or risk profile does this carry?_
Consequence is optional. When omitted, `neutral` is implied. Distinct from Evaluation: `negative` is evaluative meaning; `destructive` is outcome risk — both may appear simultaneously.
The profile codifies three values (`CONSEQUENCES` in `taxonomy.ts`) — a deliberate narrowing of the [Lexicon §6](/docs/design/design-system/fsl/fsl-lexicon#6-consequence) vocabulary, declared per FSL §13.3. The remaining Lexicon terms are rejected with the following 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 this profile, not of FSL — a different profile may codify more of the vocabulary if its component prototypes create new distinctions.
| Value | Use for |
| :-------------- | :----------------------------------------- |
| **neutral** | no special risk profile |
| **committing** | moves to a more committed state |
| **destructive** | causes deletion or materially harmful loss |
Only `Action` carries consequence — every other entity's legal set in `ENTITY_CONSEQUENCE` is empty.
---
## Interaction
`Interaction Kind` is a FSL foundational dimension ([FSL Lexicon §3](/docs/design/design-system/fsl/fsl-lexicon#3-interaction-kind), [FSL §5.3](/docs/design/design-system/fsl/fsl-structural-language)) that this profile does **not** currently codify. The disposition is **Deferred** per [FSL §13.3](/docs/design/design-system/fsl/fsl-structural-language).
Readmission requires a component that dispatches behaviour on `Interaction Kind` at runtime — for example, a Wizard that progresses on `navigate.step` versus a Link that follows `navigate.link`. Until such a prototype exists, the dimension carries no expressible distinction in `ComponentMeta`. See `taxonomy.ts` §Dimension Coverage for the full rationale.
---
## State
State answers: _What interactional or semantic condition is currently active?_
State is not a prop passed at the expression level — it is runtime-resolved by React Aria render props (`isHovered`, `isFocused`, `isPressed`, `isSelected`, …) and surfaced as the CSS selector layer:
| State | Meaning |
| :---------------- | :----------------------------------------------------------------------------------------- |
| **default** | No special condition active |
| **hover** | Pointer is over the element |
| **active** | Element is being activated / pressed |
| **focused** | Element has keyboard focus |
| **disabled** | Element is not interactive |
| **selected** | Item is selected within a collection |
| **pressed** | Toggle is in its on-press state |
| **checked** | Checkbox-like element is checked |
| **indeterminate** | Mixed or partial selection state |
| **expanded** | Disclosure or select is open |
| **current** | Navigation item matches the current location |
| **visited** | Link has been previously visited (CSS-only — browsers hide `:visited` from JS; see below) |
| **droptarget** | Element is a valid target for a drag operation |
| **invalid** | Control's value failed validation (runtime — `isInvalid`, never authorial; Lexicon §10.15) |
Not all states are meaningful for every Entity — `checked` is only surfaced by selection components. Legality here is React Aria's runtime concern (it only emits the render-prop for applicable primitives), not a build-time matrix — the declared legality source per FSL Structural Language §10.1 is **runtime resolution** — with one exception: `visited` cannot be runtime-resolved at all. Browsers hide `:visited` state from JavaScript for privacy, so no library can emit the flag; its legality source is **structural impossibility** (§10.1), declared below.
### Concurrent states and resolution order
React Aria may report several state flags simultaneously (an item can be selected, focused, and hovered at once). The profile resolves them through `STATE_PRIORITY` (`taxonomy.ts`) — a declared, deterministic total order, as FSL Structural Language §11.4 requires. `isSelected` resolves **context-aware**: the theme declares `selected` where a ux context means membership in a set (`navigation`, `informational`) and `checked` where a control is two-state (the `input` context), so the cascade consults the token set per colour dimension with an explicit fallback — `checked` when the set declares it, then `selected` when the set declares it, then the normal miss to `default` (fsl-ui ADR-044). The transient `isPressed` flag deliberately resolves to `active` — a semantic reservation, not a theme gap: the `pressed` token state means the **persistent** toggle-on, which `ToggleButton` reads by mapping its `isSelected` to `pressed` inline (fsl-ui ADR-042) and which the theme ships divergent from `active` on purpose; the collapse keeps the persistent state reserved for toggle semantics. Readmission criterion: a component whose **transient** press must paint differently from `active` at the token level. Two vocabulary states have no render-prop flag, for different reasons: `droptarget` because no component surfaces a drag target yet, and `visited` because no flag can ever exist — browsers hide `:visited` from JS for privacy, making it a **structural impossibility** per §10.1 rather than a pending flag; its tokens are spent through the CSS pseudo-class, outside the cascade. Per §11.4 these resolutions and absences are recorded here rather than silent.
---
## How to use the model
#### 1. Set Entity
Classify the component itself.
- `Button` → `Action`
- `SearchField` → `Input`
- `Menu` → `Collection`
- `Dialog` → `Overlay`
#### 2. Add Composition when the instance occupies a slot in a composite
- `Button` in a dialog footer → `composition: 'primaryAction'`
- `Button` as a form submit → `composition: 'primaryAction'`
- TextField validation message → `composition: 'status'`
- Checkbox inside a RadioGroup-like set → `composition: 'selection'`
Legal values depend on the component's Entity — see the Composition roles table above.
#### 3. Add Evaluation when the default inference isn't right
Most expressions don't need explicit Evaluation. Add it when the standard inference is wrong:
- Destructive confirm button → `evaluation: 'negative'`
- Success state feedback → `evaluation: 'positive'`
- Subdued ghost action → `evaluation: 'muted'`
#### 4. Add Consequence when the interaction carries a material risk profile
- Delete / irreversible action → `consequence: 'destructive'`
- Save with no undo → `consequence: 'committing'`
---
## Usage Examples
> Token paths reference the **Semantic Token Projection** (layer 4) and are confirmed against the shipped `@ttoss/fsl-theme`.
#### Dialog footer buttons
```ts
// Save
{ entity: 'Action', composition: 'primaryAction' }
// → action.primary.background.default, action.primary.text.default
// Back to editing
{ entity: 'Action', composition: 'secondaryAction' }
// → action.secondary.background.default, action.secondary.text.default
// Cancel
{ entity: 'Action', composition: 'dismissAction' }
// → action.muted.text.default
```
#### TextField (Input composite)
```ts
// Main control
{ entity: 'Input', composition: 'control' }
// → input.primary.background.default, input.primary.border.default, input.primary.text.default
// Label
{ entity: 'Input', composition: 'label' }
// → input.primary.text.default
// Helper text
{ entity: 'Input', composition: 'description' }
// → input.muted.text.default
// Validation message
{ entity: 'Input', composition: 'status' }
// → input.negative.text.default
```
#### Dialog (Overlay composite)
```ts
// Heading
{ entity: 'Overlay', composition: 'heading' }
// → informational.primary.text.default
// Body
{ entity: 'Overlay', composition: 'body' }
// → informational.primary.text.default
```
#### Form (Structure composite)
```ts
// Actions row container
{ entity: 'Structure', composition: 'supporting' }
// → informational.muted.background.default
// Submit button inside the actions row
{ entity: 'Action', composition: 'primaryAction' }
// → action.primary.background.default
```
#### Destructive action
```ts
{
entity: 'Action',
composition: 'primaryAction',
evaluation: 'negative',
consequence: 'destructive',
}
// → action.negative.background.default, action.negative.text.default
// A `destructive` consequence authorises downstream safe-default treatment of the cancel path.
```
---
## Rules
1. **Entity is always primary.** It defines the component, not the instance.
2. **Composition names a slot, not the component.** Composition never replaces Entity.
3. **Composition legality is per Entity.** A role is only valid on the Entities listed in the Composition roles table (source: `ENTITY_COMPOSITION`).
4. **Evaluation is semantic, not visual.** Choose it for its meaning, not its color.
5. **Consequence is about outcome risk.** It shapes interaction policy before styling.
6. **Keep the model small.** New values must come from the FSL foundation or be added through FSL governance.
> **Implementation:** See [UI Components](/docs/design/ui-components) for how this model is realized in React.
---
## Icon
:::info Status: public component in `@ttoss/fsl-ui`
`Icon` is a **public export** of `@ttoss/fsl-ui` (ADR-010): Iconify is the official glyph provider (default set: Lucide), consumed via intents (`icon.{family}.{intent}`) registered offline — no runtime API fetch. The standalone `@ttoss/fsl-icon` package remains **deferred**; the semantic layer (`intents.ts` + `glyphs.ts`) stays free of React and token imports so it can be lifted out whole. The registry below is the **shipped** vocabulary and grows on component demand (see Change Rules). See `@ttoss/fsl-ui` CONTRIBUTING ADR-005 and ADR-010.
:::
**Entity: Structure**
Icon is a **semantic visual component** that renders a glyph to reinforce meaning in the interface.
An Icon does not carry interactive behavior. It receives design tokens (color, sizing) from the context where it participates. It is defined by **what it means**, not by what it looks like.
---
## Position in the System
Icon is a component — not a design token.
A design token is a serializable value that resolves to CSS (a color, a size, a spacing unit). An Icon renders visual UI and consumes design tokens. That makes it a component.
```text
design tokens (color, sizing, motion) → Icon component → rendered SVG
```
Icon occupies the same architectural position as Button, Checkbox, or any other ttoss component. The difference is that Icon has a unique **semantic contract** — a fixed vocabulary of intents — because it is consumed pervasively across the system by other components and patterns.
---
## Component Identity
| Dimension | Value |
| :------------------- | :---------------------------------------- |
| **Entity** | Structure |
| **Behavioral class** | static |
| **Renders** | SVG glyph (`` with `currentColor`) |
| **Interactive** | No — Icon is never interactive on its own |
Icon is `Structure` because it organizes visual meaning within other components. It does not trigger actions, accept input, or manage navigation. When an icon appears inside a Button, the Button owns the interaction — the Icon provides visual reinforcement.
---
## Semantic Contract
The Icon component exposes a fixed vocabulary of **intents**. Each intent has a stable meaning that does not change across themes, providers, or implementations.
The intent determines **what the icon means**. The theme determines **which glyph renders**. The context determines **size and color**.
### Intent Structure
```text
icon.{family}.{intent}
```
- `family`: semantic group (action, navigation, disclosure, ...)
- `intent`: specific stable meaning (search, back, expand, ...)
### Families
| Family | Meaning |
| :----------- | :--------------------------------------------------------------- |
| `action` | Direct user actions |
| `navigation` | Movement and wayfinding |
| `disclosure` | Expand/collapse |
| `selection` | Checkbox/radio-like control states |
| `status` | Foundation status indicators |
| `visibility` | Show/hide — named by the contract, no shipped intents yet |
| `object` | Minimal cross-product object references — no shipped intents yet |
---
## Canonical Intent Registry
This registry is the stable public API of the Icon component — the **shipped** vocabulary, mirrored from `ICON_INTENTS` in `packages/fsl-ui/src/components/Icon/intents.ts` (on divergence, the code wins). Themes must provide a glyph for each. The registry **grows on demand**: an intent is admitted when a shipped component needs it, never speculatively — and it shrinks never (see Change Rules).
### action
| Intent | Meaning |
| :--------------- | :-------------------------------------------------------------------- |
| `close` | Dismiss a UI surface without implying deletion |
| `search` | Initiate search or represent search as primary action |
| `increment` | Step a value up |
| `decrement` | Step a value down |
| `sortAscending` | Sort a collection column in ascending order |
| `sortDescending` | Sort a collection column in descending order |
| `more` | Additional actions behind a trigger — the overflow affordance |
| `help` | Explanatory content behind a trigger — the contextual-help affordance |
### navigation
| Intent | Meaning |
| :----- | :---------------------------------------------------------------------------------- |
| `menu` | Reveal a navigation region that has no room to stand on its own (temporary sidebar) |
### disclosure
| Intent | Meaning |
| :--------- | :--------------------------------- |
| `expand` | Reveal hidden or collapsed content |
| `collapse` | Hide previously revealed content |
### selection
| Intent | Meaning |
| :-------------- | :------------------------ |
| `checked` | Affirmative checked state |
| `indeterminate` | Mixed or partial state |
### status
| Intent | Meaning |
| :-------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| `success` | Positive outcome or confirmed completion |
| `alert` | Needs attention — the invalid-field mark and any caution indicator |
| `info` | Noteworthy, judgement-free status ("in progress", "new") — a system report, distinct from the `action.help` affordance (an offer) |
---
## Token Consumption
Icon is a component that **consumes** design tokens. It does not produce them.
### Color
Icon renders with `currentColor`. It inherits color from its parent context via CSS. No color prop, no color token on the Icon itself.
When an Icon renders inside a host component's part (e.g. a menu item's supporting visual), its color comes from the color token the host part resolves (e.g. `informational.muted.text.default`). When it renders inside a `Feedback` component, it inherits the feedback color. **The context owns the color, not the Icon.**
### Sizing
Icon consumes the sizing tokens from the `icon` family:
| Token | Typical use |
| :--------------- | :------------------------- |
| `sizing.icon.sm` | Dense UI, small glyphs |
| `sizing.icon.md` | Standard icons |
| `sizing.icon.lg` | Prominent or display icons |
These map to `core.sizing.ramp.ui` steps and are fluid (responsive via `clamp()`).
### Motion
Icon does not define motion. If an Icon needs animated behavior (e.g. a spinner rotation, a disclosure chevron rotation), the host component applies motion tokens via CSS. The Icon itself is a static glyph.
---
## Composition
Icon participates in composition through the standard [Component Model](/docs/design/design-system/components/component-model): the host component owns the part the Icon renders in (exposed in the DOM via `data-scope`/`data-part`), and that part resolves the tokens the Icon inherits.
| Host component part | Typical use |
| :-------------------------------- | :---------------------------- |
| Input field `leadingAdornment` | Search icon before an input |
| Input field `trailingAdornment` | Clear icon after an input |
| Collection item supporting visual | Icon beside a menu item label |
| Feedback surface status | Status icon in a banner |
When Icon renders outside any host part, it resolves tokens from its Entity default (`Structure`):
- color: `informational.primary.text.default`
- sizing: `sizing.icon.md`
Host parts refine these defaults. For example, a collection item's supporting visual resolves to `informational.muted.text.default` + `sizing.icon.md`.
---
## Theme Mapping
Each theme provides a **glyph mapping** — a complete record that assigns a renderable glyph to every canonical intent.
The theme does not modify the semantic contract. It only decides **which visual asset** expresses each intent.
### What a theme provides
A flat mapping from intent to glyph. The glyph is a renderable unit: an inline SVG function component, an Iconify ID resolved at build time, a registered icon reference, or any other provider-specific representation.
```text
theme glyph mapping:
action.close → (x glyph)
action.search → (magnifying glass glyph)
disclosure.expand → (chevron-down glyph)
selection.checked → (check glyph)
...every intent must be mapped
```
### Theme completeness rule
A theme glyph mapping must cover **every canonical intent**. Missing intents are a contract violation. This is enforced by the type system at compile time and by validation tests at build time.
### Provider agnosticism
The contract does not prescribe how glyphs are stored or rendered. A theme may use:
- Inline SVG function components (zero runtime deps, SSR-native)
- Iconify icon data extracted at build time
- Direct imports from icon libraries (Lucide, Phosphor, Material Symbols, etc.)
- Custom hand-drawn SVGs
- Sprite references
The theme decides. The contract enforces completeness and meaning, not format.
---
## Design Rules
### 1. Intent first
Icon intents express **meaning**, not glyph appearance.
Valid: `icon.action.search`, `icon.navigation.menu`, `icon.status.alert`
Invalid: `icon.chevron-left`, `icon.close-filled`, `icon.magnifying-glass`
### 2. No provider coupling
Intents must not encode icon library names, SVG filenames, provider IDs, or style variants (`filled`, `outlined`, `duotone`). Those belong to the theme glyph mapping.
### 3. No slot semantics
Intents must not encode placement (`leading`, `trailing`, `only`, `toolbar`). Placement belongs to the Component Model composition roles.
### 4. No parallel state language
Icon must not duplicate state meaning owned by colors, borders, motion, or component API state. `icon.status.alert` is valid. `icon.alert.hovered.primary.outlined` is not.
### 5. Oppositions must be explicit
These pairs must never collapse to the same resolved glyph:
- `expand` ≠ `collapse`
- `checked` ≠ `indeterminate`
- `increment` ≠ `decrement`
- `sortAscending` ≠ `sortDescending`
- `success` ≠ `alert`
An offer is not a report: `action.help` and `status.info` may share a glyph (the default mapping's ⓘ), because the opposition rule governs pairs that must never be confused with each other — that is the theme's choice, not the intents'.
### 6. Semantic naming, not metaphor
Name by intent, not by pictogram. `close` is semantic. `x-mark` is not.
### 7. Keep `object.*` narrow
`object.*` exists for broad foundation semantics only. Domain-specific objects belong in patterns or application-level extensions.
---
## Extensibility
Applications may extend the canonical registry with domain-specific intents.
### Extension rules
1. Check if an existing intent already expresses the need before creating a new one
2. New intents must follow the same `{family}.{intent}` grammar
3. Extensions must not shadow or redefine canonical intents
4. Extensions may add new families when no existing family fits
5. Extended mappings must still satisfy the completeness rule for all canonical intents
```text
// Application extension example:
canonical intents + app intents
icon.action.close icon.product.cart
icon.action.search icon.product.wishlist
icon.status.success icon.product.inventory
... ...
```
---
## Validation
### Errors (must fail)
- Any canonical intent missing from a theme glyph mapping
- Any opposition pair resolving to the same glyph:
- `disclosure.expand` = `disclosure.collapse`
- `selection.checked` = `selection.indeterminate`
- `action.increment` = `action.decrement`
- `action.sortAscending` = `action.sortDescending`
- `status.success` = `status.alert`
### Warnings (should warn)
- Two different intents resolving to the same glyph without explicit justification
- `object.*` growing beyond a small foundation vocabulary
- An extension introducing intents that duplicate existing canonical meaning
---
## Change Rules
- Add an intent only when no existing intent can express the need
- Change a glyph mapping freely (themes evolve independently)
- Change intent meaning only by creating a new intent and deprecating the old one
- Remove an intent only through explicit deprecation and versioned breaking change
- The canonical registry grows slowly and shrinks never
---
## Summary
Icon is a **Structure component** with a fixed semantic contract.
- It renders a glyph determined by the theme
- It receives color from context via `currentColor`
- It receives size from `sizing.icon.*` tokens
- It participates in composition through the standard Component Model
- It is never interactive on its own
- Themes must map every canonical intent to a glyph
- The intent vocabulary is stable, provider-agnostic, and small by design
- Applications may extend intents but must not shadow canonical ones
---
## Components
# ttoss Components
**ttoss Components** is the semantic, token-native component framework of ttoss.
It defines the **public UI layer** of the system.
**Core Tokens → Semantic Tokens → Components → Patterns → Applications**
That is the model.
- **Core tokens** define raw values.
- **Semantic tokens** define usage.
- **Components** define reusable UI contracts.
- **Patterns** compose components into task-level solutions.
- **Applications** build products from that system.
## Position
ttoss Components exists to keep UI **stable, reusable, and scalable** across themes, products, and implementations — a stable public layer above tokens and below patterns.
It is a **semantic framework first**.
Official component libraries are **reference implementations** of that framework.
The role of ttoss Components is not to publish every possible widget.
Its role is to define a small, durable public layer of UI meaning: few components, built well, instead of many with uneven maturity.
## What makes a ttoss component
A ttoss component is a **reusable semantic contract** built on semantic tokens.
A public component must be:
- **semantic** — defined by purpose and interaction meaning
- **token-native** — built from semantic tokens only
- **accessible** — accessibility belongs to the component contract
- **durable** — stable across themes, brands, and implementation changes
- **reusable** — worth standardizing beyond a single product
If it does not meet those conditions, it does not belong in the public ttoss surface.
## Core rules
### Components consume semantic tokens only
Components never consume core tokens directly.
Core tokens define values.
Semantic tokens define usage.
Components consume semantics.
### Public meaning belongs to ttoss
The meaning of a public component is defined by ttoss.
Implementation packages may evolve.
The public contract must remain stable.
### Semantics come before styling
A component is defined by what it means and what it enables.
Styling is an implementation of that meaning.
It is not the source of the contract.
### Accessibility is part of the contract
Accessibility is part of the component itself, not a later enhancement.
A public component must preserve the accessibility expectations of its role and interaction.
### The public surface stays small
The public catalog is intentionally selective.
A component becomes public only when it is clearly reusable, semantically stable, and worth the long-term cost of support.
## Component model
ttoss Components is organized by the [Component Model](./component-model):
- **Entity** defines component identity (immutable per component).
- **Composition** names the slot an instance occupies inside a composite — a flat vocabulary with per-Entity legality; there is no `Host` level in the data model (parent disambiguation happens in the DOM via `data-scope`/`data-part`).
This keeps the public model small, explicit, and durable. Implemented by `@ttoss/fsl-ui` (`taxonomy.ts` + `ComponentMeta`).
## Variants
ttoss does not use a single global visual menu of variants.
Variants are **small semantic axes defined per Entity**, only when they represent a real reusable distinction.
That means:
- variants are Entity-specific
- variants are semantic
- variants are not a dumping ground for visual options
- state is not variant
The system starts by asking:
- what Entity does this belong to?
- what type of component is it?
- what semantic distinctions actually matter here?
Not every component needs variants.
Not every difference deserves a public axis.
## Patterns stay above components
Components and patterns are different layers.
A **component** is a reusable unit of UI meaning.
A **pattern** is a composition of components used to solve a broader interface problem.
ttoss Components owns the component layer.
It does not collapse patterns into the base component catalog.
## Reference implementations
ttoss may provide official implementation packages, such as React and web packages.
Those packages realize the system.
They do not define it.
The system is defined by its semantic contracts.
Implementation technology is replaceable.
> **Current reference implementation:** See [UI Components](/docs/design/ui-components) for the React implementation of ttoss Components.
## Local application layer
Applications need flexibility.
The official escape hatch of ttoss Components is the **local application layer**.
Applications may create:
- local patterns
- local components
- product-specific compositions
These local solutions remain outside the public ttoss surface unless they later prove reusable, stable, and semantically mature enough to be promoted.
This keeps ttoss flexible without weakening the public system.
---
## Colors
Colors define the semantic roles of color in analytical contexts.
They encode recurring analytical meaning across charts, dashboards, and geospatial overlays without coupling the system to chart types or rendering libraries.
This category is the primary semantic API of Data Visualization.
---
## Purpose
Data Visualization colors standardize how analytical meaning is represented through color.
They govern:
- categorical identity
- ordered magnitude
- midpoint comparison
- analytical references
- contextual emphasis
- data status
They do **not** define chart types, chart behavior, or full map styling.
## Scope
This category governs semantic color roles for:
- categorical series
- sequential scales
- diverging scales
- analytical references
- analytical states
- data status
This category does **not** govern:
- chart-specific color logic
- heatmap or choropleth implementation details
- statistical classification methods
- legend behavior
- basemap design
- forecast or uncertainty behavior by color alone
Those concerns belong to patterns and implementation.
## Principles
### Semantic-first
Tokens express analytical meaning, not palette names or visual styling.
### Task-first
Color roles are defined by the analytical task they support, not by chart type.
### Small and explicit
Only stable, recurring color semantics are tokenized.
### Color is primary, not sufficient
Color provides the main analytical signal, but critical meaning must still be supportable through other encodings when needed.
### Distinguish meaning classes
Categorical identity, ordered magnitude, midpoint comparison, and data absence are different semantic problems and must not be collapsed into one system.
## Model
Colors follow the same extension model as the category:
```text
core.colors → semantic.dataviz.color
patterns/specs → consume semantic only
```
### Core
Analytical color comes from `core.colors.*` — the same palette foundation used by the UI.
This keeps color values in a single location and makes dataviz palettes automatically consistent with the brand.
Core tokens are value-only and themeable.
### Semantic
Semantic tokens define analytical roles.
They form the public API of the category and must reference core tokens only.
---
## Palette Source
Analytical colors come from `core.colors.*` — the same foundation palette used by UI semantics.
The hue families used by dataviz (brand, red, orange, yellow, green, teal, purple, pink, neutral) must be provided in `core.colors` when building the theme.
Core color tokens must remain context-free and value-only.
---
## Semantic Tokens
```text id="e8cg09"
dataviz.color.series.1..8
dataviz.color.scale.sequential.1..7
dataviz.color.scale.diverging.neg3
dataviz.color.scale.diverging.neg2
dataviz.color.scale.diverging.neg1
dataviz.color.scale.diverging.neutral
dataviz.color.scale.diverging.pos1
dataviz.color.scale.diverging.pos2
dataviz.color.scale.diverging.pos3
dataviz.color.reference.baseline
dataviz.color.reference.target
dataviz.color.state.highlight
dataviz.color.state.muted
dataviz.color.state.selected
dataviz.color.status.missing
dataviz.color.status.suppressed
dataviz.color.status.notApplicable
```
These tokens form the semantic contract for analytical color.
---
## Families
### Series
`series.*` defines categorical identity.
Use series colors for:
- nominal categories
- distinct groups
- named series in charts or maps
Series colors are discrete and non-ordered.
They must not imply magnitude, ranking, or midpoint comparison.
### Sequential Scale
`scale.sequential.*` defines ordered magnitude from low to high.
Use sequential scales for:
- ordered values
- progressive intensity
- quantitative or ordinal ranges where one direction is semantically meaningful
Sequential scales must preserve perceptual order.
Lower and higher steps must remain visually interpretable as part of the same ordered continuum.
### Diverging Scale
`scale.diverging.*` defines ordered comparison around a meaningful midpoint.
Use diverging scales only when the data has a true center, such as:
- zero
- baseline
- benchmark
- target delta
Diverging scales must not be used when the midpoint is arbitrary or absent.
`neutral` represents the central class.
Negative and positive sides must be interpreted symmetrically.
### Reference
`reference.*` defines supporting analytical guides.
- `reference.baseline` represents an analytical baseline
- `reference.target` represents a desired or required target
Reference colors are not primary data colors.
They exist to support interpretation.
### State
`state.*` defines analytical emphasis.
- `state.highlight` emphasizes a focal subset
- `state.muted` de-emphasizes secondary context
- `state.selected` marks explicit analytical selection
State colors must not redefine categorical identity or scale semantics.
They modify reading context, not analytical class.
### Status
`status.*` defines non-analytic data conditions.
- `status.missing` means data is absent
- `status.suppressed` means data exists but is intentionally withheld
- `status.notApplicable` means the value does not apply to the case
Status tokens are essential to avoid collapsing distinct data conditions into a single visual treatment.
They must not be used to encode zero or low values.
---
## Geospatial Use
Geospatial overlays use the same color semantics as the rest of Data Visualization.
This means:
- categorical map overlays use `series.*`
- ordered geographic intensity uses `scale.sequential.*`
- midpoint comparisons on maps use `scale.diverging.*`
- map-specific overlay emphasis may use `state.*`
- missing or suppressed geographic data must use `status.*`
`dataviz.geo.*` does not define a second color language for maps.
Geography changes context, not the semantic meaning of analytical color.
---
## Usage Rules
### 1. Use the correct semantic family
Choose colors by analytical meaning:
- categories → `series.*`
- ordered magnitude → `scale.sequential.*`
- midpoint comparison → `scale.diverging.*`
- guides → `reference.*`
- emphasis → `state.*`
- absence/withholding/inapplicability → `status.*`
Do not substitute one family for another.
### 2. Do not encode chart types
Color tokens must remain chart-agnostic.
Invalid examples:
- `bar.primary`
- `line.forecast`
- `choropleth.fill`
- `map.region.positive`
### 3. Do not overload color with complex meaning
Forecast and uncertainty must not be represented by color alone.
When those concepts are needed, use composition across categories, such as:
- color + stroke
- color + opacity
- color + pattern
### 4. Keep series bounded
`series.*` is intentionally bounded.
If the number of categories exceeds the supported set, solve the problem in the pattern layer through grouping, faceting, filtering, interaction, or another visualization strategy.
Do not expand the semantic series range casually.
### 5. Keep status distinct from value
Missing, suppressed, and not-applicable (`notApplicable`) are not value states.
They must remain visually distinguishable from:
- zero
- low values
- muted context
- unselected data
---
## Relationship to Other Categories
### Encodings
Encodings reinforce color semantics when color alone would make interpretation fragile.
### Geospatial semantics
Geospatial semantics govern how overlays interact with spatial context.
They do not redefine analytical color meaning.
### Foundation colors
Foundation UI colors and Data Visualization colors solve different problems.
UI colors express interface meaning.
Data Visualization colors express analytical meaning.
These systems must remain separate.
---
## Validation
### Errors (validation must fail when)
- diverging color semantics are structurally incomplete:
- missing `neutral`
- missing one or more negative steps
- missing one or more positive steps
- negative and positive sides have different cardinality
- any two of these status tokens resolve to the same effective value:
- `dataviz.color.status.missing`
- `dataviz.color.status.suppressed`
- `dataviz.color.status.notApplicable`
- any status token resolves to the same effective value as:
- a sequential scale step
- a diverging scale step
- `dataviz.color.state.muted`
### Warning (validation should warn when)
- `dataviz.color.series` exceeds `1..8`
- `dataviz.color.scale.sequential` exceeds `1..7`
- `dataviz.color.reference.baseline` or `dataviz.color.reference.target` resolves to the same effective value as a primary data color token
- `dataviz.color.state.highlight`, `dataviz.color.state.muted`, and `dataviz.color.state.selected` lose effective distinction
- adjacent sequential steps resolve to the same effective value
- adjacent diverging steps on the same side resolve to the same effective value
---
## Summary
Colors define the semantic roles of color in analytical systems.
They provide a stable, reusable API for representing:
- categories
- magnitude
- midpoint comparison
- references
- emphasis
- data status
By keeping these roles explicit and bounded, the system remains simple, scalable, and unambiguous across charts, dashboards, and geospatial overlays.
---
## Encodings
Encodings define non-color visual channels used to represent analytical meaning.
They exist to reinforce interpretation, improve accessibility, and reduce overreliance on color.
This category does not replace color semantics.
It complements them.
---
## Purpose
Encodings standardize recurring analytical distinctions that should not depend on color alone.
They cover:
- categorical differentiation through shape
- categorical differentiation through pattern
- semantic line treatment through stroke style
- contextual emphasis through opacity
These tokens make analytical meaning more robust across themes, display conditions, and accessibility needs.
## Scope
Encodings govern:
- non-color channels that carry stable analytical meaning
- redundant signals used alongside color
- semantic emphasis and de-emphasis
Encodings do **not** govern:
- chart-specific mark configuration
- library-specific rendering behavior
- legend layout
- direct labeling strategies
- animation behavior
- arbitrary visual styling
These concerns belong to patterns and implementation.
## Principles
### Meaning over styling
Encodings represent analytical roles, not decorative variation.
### Color is not enough
Critical distinctions must remain interpretable without depending only on color.
### Small and deliberate
Only recurring, reusable channels are tokenized.
### Compositional
Encodings work together with color and pattern logic.
They do not attempt to encode complete analytical meaning by themselves.
## Model
Encodings follow the same extension model as the category:
```text
core.dataviz → semantic.dataviz
patterns/specs → consume semantic only
```
### Core
Core tokens define raw encoding primitives:
- shapes
- patterns
- stroke styles
- opacity values
> Opacity primitives in `core.dataviz` are independent from foundation opacity tokens.
> They exist specifically to support analytical encoding and must not be used as a general-purpose transparency system.
### Semantic
Semantic tokens define analytical intent:
- series differentiation
- reference treatment
- forecast treatment
- uncertainty treatment
- contextual de-emphasis
Patterns and components must consume semantic tokens only.
---
## Core Tokens
```text
core.dataviz.shape.1..8
core.dataviz.pattern.1..6
core.dataviz.stroke.solid
core.dataviz.stroke.dashed
core.dataviz.stroke.dotted
core.dataviz.opacity.context
core.dataviz.opacity.muted
core.dataviz.opacity.uncertainty
```
Core tokens are value-only and context-free.
---
## Semantic Tokens
```text
dataviz.encoding.shape.series.1..8
dataviz.encoding.pattern.series.1..6
dataviz.encoding.stroke.reference
dataviz.encoding.stroke.forecast
dataviz.encoding.stroke.uncertainty
dataviz.encoding.opacity.context
dataviz.encoding.opacity.muted
dataviz.encoding.opacity.uncertainty
```
These tokens form the public API of the category.
---
## Families
### Shape
`shape.series.*` defines categorical distinction through form.
Use shape when:
- categories need redundant differentiation
- marks are small or dense
- color alone would be insufficient
Shape is primarily intended for point-based representations and compact categorical marks.
### Pattern
`pattern.series.*` defines categorical distinction through fill texture.
Use pattern when:
- categories appear in filled regions
- area-based marks need redundancy
- grayscale or low-color contexts must remain interpretable
Pattern is especially useful in filled analytical areas, including geospatial overlays.
### Stroke
Stroke encodes semantic treatment for line-based distinctions.
- `stroke.reference` is used for analytical guides or baselines
- `stroke.forecast` is used for projected or forward-looking segments
- `stroke.uncertainty` is used for uncertain or estimated bounds
Stroke semantics must remain visually distinct from primary data marks.
### Opacity
Opacity defines analytical emphasis, not general visual transparency.
This category introduces **analytical encoding opacity**, which is distinct from
foundation opacity used for UI behaviors such as scrims, loading states, or surface dimming.
- foundation opacity modifies interface layers and interaction states
- dataviz encoding opacity encodes analytical meaning within data representations
Opacity in Data Visualization must be interpreted as a semantic channel,
not as a styling control.
---
## Geospatial Use
Geospatial overlays use the same encoding semantics as the rest of Data Visualization.
This means:
- point-based overlays may use `shape.series.*`
- area-based overlays may use `pattern.series.*`
- spatial references may use `stroke.reference`
- uncertain spatial overlays may use `stroke.uncertainty` and `opacity.uncertainty`
- reduced map context may use `opacity.context`
`dataviz.geo.*` does not define a second encoding language for maps.
Geography changes context, not the semantic role of encoding channels.
---
## Usage Rules
### 1. Encodings are semantic, not chart-specific
Tokens must not encode chart types.
Invalid examples:
- `bar.pattern.1`
- `line.stroke.primary`
- `map.fill.texture`
### 2. Encodings complement color
Use encodings to reinforce meaning already established through semantic color or analytical role.
Encodings should not introduce a parallel, unrelated classification system.
### 3. Forecast and uncertainty require composition
Forecast and uncertainty must not rely on color alone.
They should be expressed through composition across families, for example:
- color + stroke
- color + opacity
- color + pattern
### 4. Opacity is not a free styling control
Only semantic opacity roles are allowed.
Do not create ad-hoc transparency values to tune chart appearance.
### 5. Do not mix analytical opacity with UI opacity
Analytical opacity (`dataviz.encoding.opacity.*`) must not be used for:
- UI layering
- overlays or scrims
- disabled or inactive interface states
Foundation opacity tokens must not be used to encode analytical meaning.
These systems are intentionally separate.
### 6. Keep categorical sets bounded
Series differentiation through shape and pattern must remain bounded and intentional.
If the number of categories exceeds the supported set, solve the problem at the pattern layer through grouping, filtering, faceting, or another visualization strategy.
---
## Accessibility
Encodings are part of the accessibility contract of Data Visualization.
They help ensure that:
- meaning does not depend only on color
- meaningful graphics remain distinguishable
- categories remain readable under constrained viewing conditions
Patterns and components should use encodings whenever color alone would make interpretation fragile.
## Relationship to Other Categories
### Colors
Colors provide the primary semantic roles for analytical meaning.
Encodings reinforce and stabilize that meaning.
### Geospatial semantics
Geospatial semantics govern spatial context and overlay states.
They do not replace shape, pattern, stroke, or opacity as analytical channels.
### Foundation tokens
Spacing, typography, borders, and other primitives remain part of the global foundation and are reused as needed.
---
## Validation
### Errors (validation must fail when)
- analytical opacity does not stay separate from foundation opacity:
- `dataviz.encoding.opacity.*` resolves outside `core.dataviz.opacity.*`
- foundation opacity tokens are used to encode analytical meaning
- forecast or uncertainty is introduced without composition support:
- `dataviz.encoding.stroke.forecast` or `dataviz.encoding.stroke.uncertainty` is missing when those semantics are declared
- uncertainty is modeled only by opacity without a second reinforcing channel
- `dataviz.geo.*` introduces a parallel encoding language instead of reusing:
- `dataviz.encoding.shape.*`
- `dataviz.encoding.pattern.*`
- `dataviz.encoding.stroke.*`
- `dataviz.encoding.opacity.*`
### Warning (validation should warn when)
- `dataviz.encoding.shape.series` exceeds `1..8`
- `dataviz.encoding.pattern.series` exceeds `1..6`
- `dataviz.encoding.stroke.reference`, `dataviz.encoding.stroke.forecast`, and `dataviz.encoding.stroke.uncertainty` lose effective distinction
- `dataviz.encoding.opacity.context`, `dataviz.encoding.opacity.muted`, and `dataviz.encoding.opacity.uncertainty` lose effective distinction
- the category exposes color semantics but no shape or pattern series primitives, increasing the risk that categorical meaning depends only on color
- pattern and shape series capacities are both absent, reducing redundancy options for categorical differentiation
---
## Summary
Encodings define the non-color channels of analytical meaning.
They keep the system accessible, composable, and resilient by standardizing how charts and overlays differentiate:
- categories
- references
- forecasts
- uncertainty
- context
across both generic and geospatial analytical views.
---
## Model
Data Visualization extends the Design Tokens v2 model to represent analytical meaning.
It follows the same architectural principles as the system while introducing a controlled extension for data-specific semantics.
---
## Architecture
```text
core.foundation → semantic.foundation
core.dataviz → semantic.dataviz
patterns/specs → consume semantic only
```
### Core
Core tokens define raw, themeable values.
- `core.foundation` contains global primitives such as colors, spacing, typography, borders, radii, and motion
- `core.dataviz` contains non-color encoding primitives specific to analytical visualization:
- mark shapes, fill patterns, stroke dash arrays, and analytical opacity values
- Analytical colors are sourced from `core.colors.*` — no separate dataviz color palette is needed
Core tokens must remain value-only and context-free.
### Semantic
Semantic tokens define meaning.
- `semantic.foundation` defines UI semantics
- `semantic.dataviz` defines analytical semantics
Semantic tokens:
- reference core tokens only
- express stable analytical roles
- form the public API of the category
Components and patterns must consume semantic tokens exclusively.
### Patterns and Specifications
Patterns and specifications define how tokens are applied.
They are responsible for:
- chart type selection
- multi-view composition
- legend and labeling strategies
- tooltip behavior
- interaction design
- geospatial rendering details
These concerns are intentionally out of scope for tokens.
---
## Semantic Boundary
Data Visualization tokens encode analytical meaning, not implementation.
### Included
- categorical identity
- ordered magnitude
- midpoint comparison
- analytical references
- contextual states
- data status
- non-color encodings for redundancy
- geospatial overlay semantics
### Excluded
- chart-specific configuration
- statistical methods
- rendering logic
- layout and composition rules
- visualization library behavior
- full map styling systems
---
## Core Extension Rules
Data Visualization introduces new core tokens only when all of the following are true:
1. the problem is unique to analytical visualization
2. the concept is stable across multiple chart types and domains
3. the value can be defined independently of context
This results in a minimal set of new primitives:
- encoding primitives for shape, pattern, stroke, and analytical opacity
> Analytical opacity is distinct from foundation opacity.
> Foundation opacity is used for interface layering and interaction states. Data Visualization opacity is used as an encoding channel for analytical meaning.
All other needs must reuse existing foundation tokens.
---
## Semantic Design Rules
Semantic tokens must follow these constraints.
### 1. Role-based naming
Tokens express analytical roles, not visual properties.
Examples:
- `series`
- `scale.sequential`
- `scale.diverging`
- `reference`
- `state`
- `status`
### 2. No chart-specific semantics
Tokens must not encode chart types or components.
Invalid examples:
- `bar.primary`
- `line.highlight`
- `map.region.fill`
### 3. No library coupling
Tokens must remain independent from rendering technologies.
They cannot reference:
- specific chart libraries
- map providers
- rendering engines
### 4. Composability
Complex meaning must be expressed through composition across families.
Examples:
- forecast = color + stroke + optional opacity
- uncertainty = color + opacity + pattern
No single token should attempt to encode complex analytical meaning alone.
---
## Geospatial Contract
Geospatial support follows an overlay-first approach.
Geography does not introduce a parallel semantic language for color or encoding.
It defines the contextual contract for analytical overlays on spatial surfaces.
### Geospatial layers
- **Context**: geographic background that supports orientation
- **Overlay**: analytical data rendered on top of geography
- **State**: spatial interaction such as focus and selection
### Geospatial semantic tokens
```text
dataviz.geo.context.muted
dataviz.geo.context.boundary
dataviz.geo.context.label
dataviz.geo.state.selection
dataviz.geo.state.focus
```
### Geospatial rules
1. geospatial overlays use `dataviz.color.*` for analytical color meaning
2. geospatial overlays use `dataviz.encoding.*` for non-color reinforcement
3. `dataviz.geo.*` defines only contextual spatial semantics
4. `dataviz.geo.*` must not introduce a parallel color or encoding language
### What geospatial semantics govern
- contextual reduction behind overlays
- supportive boundaries that preserve spatial reading
- contextual labels that preserve orientation
- explicit spatial focus and selection states
### What geospatial semantics do not govern
- basemap design
- projection
- tiling
- zoom and generalization algorithms
- label placement systems
- provider-specific map style behavior
---
## Validation Expectations
### Analytical
- sequential scales must preserve perceptual order
- diverging scales must center around a meaningful midpoint
- series tokens must remain within bounded sets
- status tokens must clearly differentiate absence of data
### Accessibility
- meaning must not rely on color alone
- encodings must provide redundancy when required
- critical graphical elements must remain perceptible
### Geospatial
- overlays must remain legible against supported geographic context
- context reduction must not compete with the primary analytical layer
- spatial focus and selection must remain distinguishable from the base state
---
## Summary
The Data Visualization model defines a minimal and strict semantic layer for analytical meaning.
It ensures that:
- tokens remain stable and reusable
- meaning is separated from implementation
- geospatial overlays reuse the same analytical semantics as other visualizations
- visualization systems can scale without semantic drift
By limiting scope and enforcing clear boundaries, the model provides a robust foundation for data-driven interfaces.
---
## Data Visualization
Data Visualization defines the semantic contract for representing analytical meaning across charts, dashboards, and geospatial overlays.
It extends the [design token system](/docs/design/design-system/design-tokens/model) with a small, explicit layer for data-specific semantics while preserving the same system architecture:
- core tokens define raw values
- semantic tokens define meaning
- components and patterns consume semantic tokens only
This category exists to standardize recurring analytical meaning without coupling the system to chart types, rendering libraries, or map providers.
---
## Purpose
The purpose of this category is to make analytical meaning durable, reusable, and governable.
It defines semantic roles for:
- categorical identity
- ordered magnitude
- midpoint comparison
- analytical references
- contextual emphasis
- data status
- non-color analytical encodings
- minimal geospatial overlay semantics
The goal is not to define charts.
The goal is to define the stable meaning that charts, dashboards, and overlays express.
## Scope
Data Visualization governs:
- semantic color roles for analytical data
- non-color encodings that reinforce analytical meaning
- minimal geospatial semantics for thematic overlays
Data Visualization does **not** govern:
- chart type selection
- chart-specific configuration
- visualization libraries or rendering APIs
- multi-view or dashboard composition
- tooltip behavior
- labeling strategies
- statistical transformations
- basemap design or complete cartographic systems
- map projection, tiling, or generalization logic
These concerns belong to the pattern and implementation layers.
## Principles
### Semantic-first
Tokens express analytical meaning, not stylistic preference.
### Task-first
The system models analytical roles, not chart types.
### Small and explicit
Only stable and recurring concepts are encoded.
### Accessible by design
Meaning must not depend on color alone.
### Overlay-first for geospatial
Geospatial support focuses on thematic overlays, not full cartographic systems.
### Clear boundaries
Tokens govern meaning.
Patterns and implementations govern composition and behavior.
## Architecture
Data Visualization follows the same architectural model as the rest of the system:
```text
core. → semantic. (foundation families: colors, spacing, …)
core.dataviz → semantic.dataviz (this extension)
patterns/specs → consume semantic only
```
("Foundation" here is shorthand for the existing non-dataviz families — there is no physical `foundation` key in `ThemeTokens`; see the [Token Model](/docs/design/design-system/design-tokens/model).)
### Foundation reuse
Data Visualization reuses the existing foundation wherever the problem is already solved, including:
- typography
- spacing
- sizing
- borders
- radii
- elevation
- z-index
- motion
- global opacity
### Core extension
Data Visualization introduces new core tokens only where the problem is unique to analytical visualization:
- analytical color palettes
- non-color encoding primitives
This keeps the category small and prevents parallel foundations.
---
## Semantic Surfaces
### Colors
`dataviz.color.*` defines the semantic roles of color in analytical contexts.
It governs:
- series identity
- sequential scales
- diverging scales
- analytical references
- analytical states
- data status
This is the primary semantic API of the category.
### Encodings
`dataviz.encoding.*` defines non-color channels used to reinforce meaning.
It governs:
- shape
- pattern
- stroke style
- opacity semantics
Encodings exist to improve accessibility, robustness, and perceptual clarity.
### Geospatial overlays
Geospatial overlays are part of Data Visualization.
They do not introduce a parallel color or encoding system.
Instead:
- overlays use `dataviz.color.*` for analytical color meaning
- overlays use `dataviz.encoding.*` for non-color reinforcement
- geospatial semantics define only the relationship between the overlay and spatial context
The geospatial contract is therefore contextual, not a separate visual language.
---
## Consumption Model
Components and patterns must consume **semantic dataviz tokens only**.
They must never:
- consume `core.dataviz` directly
- create chart-type tokens in product code
- introduce local analytical vocabularies that bypass the contract
If a need cannot be expressed by existing semantics, it must be handled through:
1. existing tokens
2. pattern-level composition
3. deliberate governance of new semantics
## Relationship to the Core Color System
Data Visualization colors are distinct from UI semantic colors.
- UI colors express interface meaning
- Data Visualization colors express analytical meaning
These systems must remain separate.
A negative action color is not the same thing as a negative analytical scale value.
A highlighted chart series is not the same thing as a highlighted button state.
## Relationship to Patterns
Patterns are responsible for applying Data Visualization semantics to real visualizations.
They decide:
- which chart type to use
- which encoding strategy is appropriate
- whether scales are shared or independent
- whether meaning is reinforced through labels, legends, or annotations
- how maps behave across zoom levels
Data Visualization tokens provide the semantic building blocks.
Patterns turn those blocks into complete visualization behavior.
---
## Validation
Family-specific checks such as sequential order, diverging balance, bounded pattern sets, or detailed geospatial legibility belong in their own documents.
### Errors (validation must fail when)
- Data Visualization introduces chart-type, component, library, provider, or map-style semantics in the semantic token surface
- analytical opacity does not stay separate from foundation opacity:
- `dataviz.encoding.opacity.*` resolves outside `core.dataviz.opacity.*`
- foundation opacity tokens are used to encode analytical meaning
### Warning (validation should warn when)
- `dataviz.geo.state.focus` and `dataviz.geo.state.selection` resolve to the same effective value
---
## Summary
Data Visualization is a minimal semantic extension for analytical meaning.
It exists to make charts, dashboards, and geospatial overlays more:
- consistent
- accessible
- scalable
- and semantically durable
It does this by defining a small public API for analytical meaning while keeping chart behavior, composition, and rendering outside the token layer.
---
## Borders
Border tokens define the **line system** of ttoss: the widths, styles, and semantic contracts used to separate, contain, select, and focus interface elements.
Borders must be:
- **Structural** — clarify containment and separation without replacing layout
- **Predictable** — remain small, stable, and easy to choose
- **Accessible** — support clear selected and focus states
- **Composable** — work with semantic color tokens rather than duplicating color meaning
- **Durable** — avoid component-specific drift
This system is built on **two explicit layers**:
1. **Core Tokens** — intent-free line primitives
2. **Semantic Tokens** — stable line contracts consumed by UI code
Components must always consume **semantic border tokens**, never core border tokens directly.
> **Rule:** Core border tokens are never referenced in components.
---
## Scope: line geometry only
Border tokens define the **line system** of the interface: width and style. Colour belongs to [colors](./colors.md). Edge selection (top/bottom/inline-start) belongs to components.
Two CSS mechanisms render lines, and the family covers both:
- **`border`** — lines inside the box model. Default mechanism for `divider`, `outline.{surface,control,selected}`.
- **`outline`** — lines outside the box model. Preferred mechanism for `focus.ring` (no layout shift, clearer a11y).
> The token role `outline` (a grouping under `semantic.border.*`) and the CSS property `outline` are not the same thing. The former is a namespace for at-rest boundary contracts; the latter is a render mechanism. `focus.ring` is the only contract that _must_ render via the CSS `outline` property; `border.outline.*` may render either way depending on the component.
## Pairing with colour
Border tokens carry no colour. Every visible line is a composition:
```text
stroke = semantic.border.{token}.{width,style} (geometry, this family)
+ semantic.colors.{ux}.{role}.border.{state} (colour, colors family)
```
Focus is the same composition with one difference — see [Focus Implementation](#focus-implementation) for which colour to pick.
## Core Tokens
Core border tokens are intent-free primitives.
They define the physical characteristics of lines in the system.
Borders do **not** require a responsive engine.
Line thickness should remain stable across viewport sizes to preserve consistency and accessibility.
### Core Token Set
Core border tokens are organized into three groups:
1. **Widths** — line thickness
2. **Styles** — line pattern
3. **Offsets** — gap between a box's edge and a line drawn outside it
#### Border Widths
| Token | Meaning | Recommended use |
| :--------------------------- | :--------------------- | :-------------------------------------------- |
| `core.border.width.none` | no line | borderless or reset cases |
| `core.border.width.default` | standard line width | default dividers and outlines |
| `core.border.width.selected` | stronger line emphasis | selected/current items when thickness changes |
| `core.border.width.focused` | focus ring thickness | accessible focus indicators |
#### Border Styles
| Token | Meaning | Recommended use |
| :------------------------- | :--------------- | :----------------------------------------- |
| `core.border.style.solid` | continuous line | default borders, outlines, and focus rings |
| `core.border.style.dashed` | interrupted line | optional alternate structural emphasis |
| `core.border.style.dotted` | dotted line | rare, low-frequency utility use |
| `core.border.style.none` | no visible line | reset cases |
#### Border Offsets
| Token | Meaning | Recommended use |
| :--------------------------- | :---------------------------------------- | :----------------------------------- |
| `core.border.offset.focused` | gap between a control's edge and the ring | focus ring offset (`outline-offset`) |
One member, because the focus ring is the only line the system draws outside the box. Kept independent of `width.focused` even though the base theme sets both to the same value — a theme retunes thickness for prominence and offset for how much the ring breathes off the control.
> **Naming note:** Border width names (`default`, `selected`, `focused`) look like state names but are not UI intent in the sense prohibited by model.md §1. They are positions in a four-step scale named by their canonical use-site — a deliberate choice that encodes an ordering constraint: `focused ≥ selected > default > none`. A purely ordinal scheme (`0, 1, 2, 3`) would lose this constraint from the name and JSDoc alone. Themes may remap the semantic layer (e.g., map `outline.selected.width` to `core.border.width.default` when selection is expressed through color only, not thickness) — the indirection is not ceremonial. The prohibition in §1 targets component-specific or context-specific names (`core.border.width.button`, `core.border.width.card`), not canonical use-site names in a small, closed scale.
> Keep the core set small. Border systems become unstable when too many widths or styles are introduced.
### Example
```js
const coreBorder = {
border: {
width: {
none: '0px',
default: '1px',
selected: '2px',
focused: '2px',
},
style: {
solid: 'solid',
dashed: 'dashed',
dotted: 'dotted',
none: 'none',
},
offset: {
focused: '2px',
},
},
};
```
**Expected consumption pattern:** semantic line tokens reference core border tokens by alias.
## Semantic Tokens
Semantic border tokens define the **function** of a line in the interface.
They are intentionally anchored in **structural role**, not in component names.
### Token structure
```text
{family}.{role}.{context?}
```
- `family`: `border` or `focus`
- `role`: `divider | outline | ring`
- `context`: `surface | control | selected` (only where needed)
### Canonical semantic set
- `border.divider`
- `border.outline.surface`
- `border.outline.control`
- `border.outline.selected`
- `focus.ring` — width + style + **color** + **offset**; the color field is the system-wide focus default (cross-cutting infrastructure, see [model.md §6](../model.md#6-no-parallel-vocabulary)); the offset floats the ring off the control's edge
> Keep this set stable.
> Do not introduce component-specific line tokens by default (`border.input`, `border.card`, `border.tab`, etc.).
### Semantic Tokens Summary Table
| token | use when you are building… | contract (must be true) | default mapping |
| :------------------------ | :---------------------------------------------- | :-------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- |
| `border.divider` | separators between content groups | purely structural; low emphasis | `core.border.width.default` + `core.border.style.solid` |
| `border.outline.surface` | cards, panels, dialogs, menus, grouped surfaces | defines surface boundary | `core.border.width.default` + `core.border.style.solid` |
| `border.outline.control` | buttons, inputs, toggles, interactive controls | defines control boundary | `core.border.width.default` + `core.border.style.solid` |
| `border.outline.selected` | active tabs, selected rows, chosen items | selection/current state changes thickness | `core.border.width.selected` + `core.border.style.solid` |
| `focus.ring` | keyboard focus indicators | must remain clearly visible and accessible; carries width + style + color (system default) + offset | `core.border.width.focused` + `core.border.style.solid` + `semantic.focus.ring.color` + `core.border.offset.focused` |
### Example
```js
const semanticBorder = {
border: {
divider: {
width: '{core.border.width.default}',
style: '{core.border.style.solid}',
},
outline: {
surface: {
width: '{core.border.width.default}',
style: '{core.border.style.solid}',
},
control: {
width: '{core.border.width.default}',
style: '{core.border.style.solid}',
},
selected: {
width: '{core.border.width.selected}',
style: '{core.border.style.solid}',
},
},
},
focus: {
ring: {
width: '{core.border.width.focused}',
style: '{core.border.style.solid}',
offset: '{core.border.offset.focused}',
},
},
};
```
---
## Color Pairing
Border tokens define **geometry only**.
They do not define semantic meaning through colour.
To express meaning, pair line tokens with semantic color tokens:
```css
border: var(--token-border-outline-control-width)
var(--token-border-outline-control-style)
var(--token-input-primary-border-default);
```
Typical pairings:
- `border.divider` + `informational.muted.border.default`
- `border.outline.surface` + `informational.muted.border.default`
- `border.outline.control` + `{ux}.{role}.border.default` (per the component’s `{ux}`)
- `border.outline.selected` + `{ux}.{role}.border.selected`
- `focus.ring` + focus colour — see [Focus Implementation](#focus-implementation) for the rule
> Width and style express **how strong the line is**.
> Colour expresses **what the line means**.
## Focus Implementation
`focus.ring` is a semantic line contract for keyboard/programmatic focus. It carries `width`, `style`, `color`, **and** `offset` — the colour field exists because focus needs a system-wide default that no `{ux}` owns (see [model.md §6](../model.md#6-no-parallel-vocabulary)); the offset (rendered as `outline-offset`, aliasing `core.border.offset.focused`) floats the ring off the control so it stays legible against the control's own fill and its contrast pairing is against the stratum behind.
Render via CSS `outline`, not `border`: outlines sit outside the box, avoid layout shift, and produce clearer a11y indicators.
### Which focus colour
| The component is… | Use |
| :---------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |
| an `Action` / `Input` / `Navigation` / `Feedback` (clear FSL Entity Kind) | `{ux}.{role}.border.focused` from `semantic.colors.*` |
| an `Informational` surface made interactive (focusable Card, profile chip, custom widget) | `semantic.focus.ring.color` (system default) |
| an `Input` with `negative` or `caution` valence where focus must inherit the valence | `input.{negative\|caution}.border.focused` (overrides the system default) |
The two paths are not duplicates — per-context tokens answer "how does _this_ `{ux}` look when focused?"; `focus.ring.color` answers "what is the _system_ default when no `{ux}` applies?". Pick by which question the component is asking.
### Example
```css
/* Focusable profile card — no obvious {ux}: use the system default */
.card:focus-visible {
outline-width: var(--tt-focus-ring-width);
outline-style: var(--tt-focus-ring-style);
outline-color: var(--tt-focus-ring-color);
outline-offset: var(--tt-focus-ring-offset);
}
/* Input in error — negative valence overrides the system default */
.input--error:focus-visible {
outline-width: var(--tt-focus-ring-width);
outline-style: var(--tt-focus-ring-style);
outline-color: var(--tt-input-negative-border-focused);
outline-offset: var(--tt-focus-ring-offset);
}
```
> A row inside a clipped or scrolling container has nowhere to put the gap and insets the ring by its own width instead — a component decision derived from `width`, not a second token.
## Scope: Tokens vs Components vs Edge Selection
Line tokens define **line contracts**.
They do not define component-specific APIs.
- **Design tokens** define widths, styles, and semantic line roles
- **Components** choose where the line is applied (all sides, top only, bottom only, etc.)
- **Patterns** may decide which edge carries the line
This means:
- edge selection belongs to the component or pattern layer
- line tokens remain stable and reusable
- the token system avoids exploding into edge-specific or component-specific names
> Example: an active tab may consume `border.outline.selected`, while the tab component decides that the line appears only on the bottom edge.
## Rules of Engagement (non-negotiable)
1. **Semantic-only consumption:** components use semantic line tokens only
2. **Color meaning stays in the color system:** line tokens never encode error/success/warning meaning by themselves
3. **Focus is distinct from outline-at-rest:** `focus.ring` is a dedicated semantic contract
4. **Do not create component-specific line tokens by default:** avoid `border.input`, `border.card`, `border.table`, etc.
5. **Do not use borders as a substitute for layout:** use spacing and structure first; borders complement separation
6. **Do not overuse style variation:** default to `solid`; use `dashed` or `dotted` only when the pattern truly needs it
## Decision Matrix
1. **Separating groups of content?** → `border.divider`
2. **Default boundary of a containing surface?** → `border.outline.surface`
3. **Default boundary of an interactive control?** → `border.outline.control`
4. **Selected/current state shown through stronger thickness?** → `border.outline.selected`
5. **Keyboard/programmatic focus indicator?** → `focus.ring` for geometry; for colour, see [Which focus colour](#which-focus-colour)
## Usage Examples
| Usage | Token |
| :----------------------------- | :------------------------ |
| Card or panel outline | `border.outline.surface` |
| Input or button outline | `border.outline.control` |
| Divider between content groups | `border.divider` |
| Selected tab / active row | `border.outline.selected` |
| Focus ring | `focus.ring` |
> Build output may expose semantic line tokens as CSS variables or framework-specific bindings. The semantic names remain the API.
## Advanced CSS Capabilities (escape hatches, not token contracts)
CSS supports more line complexity than the ttoss foundation exposes by default, including:
- per-side borders
- multiple width values
- separate outline properties
- offset outlines
These are valid implementation capabilities, but they are **not part of the canonical semantic token contract**.
Use them only when layout, interaction, or accessibility truly requires them.
Examples:
- `border-bottom-width`
- `border-inline-start`
- `outline`
- `outline-offset`
> If a pattern repeatedly needs specialized edge logic, solve it at the pattern/component layer first — not by expanding the foundation tokens prematurely.
## Theming
Themes may tune:
- core border widths (`core.border.width.*`)
- core border styles (`core.border.style.*`)
- semantic mappings if the overall line language of the brand changes
Semantic token names **never change across themes**.
---
## Validation
### Errors (validation must fail when)
- `border.outline.selected` resolves to a width weaker than `border.outline.{surface,control}`
- `focus.ring` resolves to a width weaker than `border.outline.*`
- `border.outline.selected` resolves to `none`, `0`, or an equivalent non-visible line
- `focus.ring` resolves to `none`, `0`, or an equivalent non-visible line
- generated output collapses `focus.ring` and `border.outline.*` into the same effective line contract
### Warning (validation should warn when)
- `border.outline.selected` resolves to the same effective line contract as the resting outline
- `focus.ring` resolves to the same effective line contract as the resting outline
---
## Summary
- Core tokens define the available line widths and styles
- Semantic tokens define a small set of stable line contracts
- Border color remains in the color system
- Focus is a dedicated semantic contract and is usually implemented with `outline`
- Edge-specific behavior belongs to components and patterns, not to the foundation tokens
- The system stays small, predictable, and scalable
---
## Breakpoints
Breakpoints define **viewport thresholds** for macro layout changes — page structure, grid columns, navigation modes, and major structural reflows. They are **adaptation infrastructure**, not visual design tokens.
Unlike color, typography, or spacing, breakpoints do not express durable UI meaning. They do **not** define a semantic layer in the foundation. Applications may adjust or replace them based on real layout needs, and any local aliases (e.g., `navCollapse`, `shellWide`) stay in the application layer.
> **Key principle:** Breakpoints define _when_ layout changes, not _how_ components behave.
### Responsive tool selection
| Need | Tool |
| :------------------------------------------ | :--------------------------------- |
| Whole layout changes at viewport thresholds | **Breakpoints** |
| A single component needs to adapt | **Container queries** |
| A value should scale continuously | **Fluid tokens** |
| Many viewport thresholds for one component | Wrong tool — use container queries |
---
## Foundation Default Set
The foundation exports a default breakpoint baseline in **`rem`** to reduce setup friction and provide a shared starting point. It is a recommended default — easy to use, easy to replace, not semantically locked.
| Token | Value |
| :---- | :------ |
| `sm` | `30rem` |
| `md` | `48rem` |
| `lg` | `64rem` |
| `xl` | `80rem` |
| `2xl` | `96rem` |
Base layout applies below `sm` (mobile-first, no `xs` token needed).
```js
const breakpoints = {
sm: '30rem',
md: '48rem',
lg: '64rem',
xl: '80rem',
'2xl': '96rem',
};
```
---
## Usage
### CSS
```css
@media (min-width: 48rem) {
.layout {
grid-template-columns: 240px 1fr;
}
}
```
### UI logic
```js
columns: {
base: 1,
md: 2,
xl: 3,
}
```
---
## Rules
1. **Content-first** — define breakpoints where the layout breaks, not by device categories. Avoid `mobile`, `tablet`, `desktop` naming.
2. **Mobile-first** — base styles apply below `sm`. Scale up using `min-width`.
3. **Viewport-only** — do not use breakpoints for component-level responsiveness.
4. **Keep it small** — most systems need 4–5 breakpoints maximum.
5. **Not themed** — breakpoints are layout infrastructure, not brand expression. Adjust per-product at application or layout-system level.
6. **Local aliases stay local** — application-specific names like `content` or `navCollapse` do not belong in the foundation.
---
## Application-level Adaptation
Breakpoints are one of the few token families where **local optimization is expected**. An application may change threshold values, remove unused breakpoints, add new ones if layout truly requires it, or define local aliases for readability.
Guidelines: choose breakpoints where layout becomes constrained, validate with real content, keep thresholds consistent within the application, and avoid expanding the scale casually.
### Foundation vs Application ownership
| Foundation owns | Application owns |
| :------------------------------------------------- | :------------------------------------------------- |
| Default baseline and naming (`sm`–`2xl`) | Local threshold tuning |
| `rem` recommendation | Local aliases for layout intent |
| Rules that keep the scale small and content-driven | Product-specific additions and responsive strategy |
---
## Validation
### Errors (must fail)
- Breakpoint order breaks: `sm >= md`, `md >= lg`, `lg >= xl`, or `xl >= 2xl`
- Any foundation breakpoint resolves to `0` or a negative value
### Warnings (should warn)
- Adjacent steps differ by less than `8rem`
- Foundation set contains more than `5` named steps
- Any foundation breakpoint does not resolve to a `rem` value
- Device-category naming detected (`mobile`, `tablet`, `desktop`)
---
## Colors(Families)
Colors define the **semantic color language** of ttoss — brand identity, hierarchy, interaction meaning, contrast, state.
The system has **two layers**: **Core Colors** (intent-free palette primitives) and **Semantic Colors** (stable contracts consumed by UI code). Components consume semantic colors only — never core directly.
---
## UX contexts in 60 seconds
Every semantic color token starts with a **UX context** — a plain description of _what kind of UI_ the color is for. There are five, and they cover the whole surface area of a UI:
| UX context | Use it for | Typical components |
| :-------------- | :----------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- |
| `action` | anything the user **triggers** | buttons, toggles, menu items, action icons |
| `input` | anything the user **enters or selects data into** | text fields, selects, checkboxes, radios |
| `navigation` | anything that **moves the user** between views or sections | links, tabs, breadcrumbs, pagination |
| `feedback` | surfaces that **report the outcome** of an action or system event | toasts, alerts, banners, inline validation |
| `informational` | **presentational surfaces** — hold, group, layer, frame, or display content; never drive a transaction | body text, page backgrounds, cards, panels, dialogs, dividers, list rows, accordions |
Picking a context is usually trivial: _"is the user about to act, type, move, hear back, or just **see/contain** something?"_
> **Interactivity is not a tiebreaker.** A focusable Card, clickable panel, or expandable accordion is still `informational` — its _purpose_ is presentational. Focusability and disclosure are orthogonal capabilities (covered by `focus.ring.color` and the `expanded` state).
> **Advanced.** The five contexts are a formal projection of the nine FSL Entity Kinds — see [FSL Entity Kind Mapping](#fsl-entity-kind-mapping) below. Most component authors never need to read the FSL layer.
---
## Scope
Colors carry **meaning and visual contrast** — nothing else. Depth lives in `elevation`, line geometry in `borders`, whole-element transparency in `opacity`, charts in data visualization tokens. Color may pair with those families; it does not replace them.
> **Color names express intent, not appearance.**
---
## Core Colors
Core colors are **intent-free primitives** — they define which colors exist in a theme (brand, neutral, hue scales) at sufficient depth for semantic remapping across modes, but not where they are used.
### Core token structure
```text
core.colors.{family}.{scale}
```
- `family`: a palette family such as `brand`, `neutral`, `red`, `green`, `blue`
- `scale`: an ordered step inside that family
### Core groups
A theme MUST define `brand` and `neutral`; hue families are open. Add a hue family only when needed to support a concrete semantic mapping.
| Family | Role in the palette | Required steps |
| :-------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------- |
| `brand` | Identity hue. Depth allows light/dark remapping without new values. | open subset across `100..900` |
| `neutral` | Zero-saturation anchor for surfaces, text contrast, dividers, subdued UI. Step `0` = white-end, `1000` = black-end, `500` = canonical mid. | step `500` mandatory; others open |
| Hue scales (`red`, `orange`, `green`, `yellow`, `teal`, `purple`, `pink`, \u2026) | Optional palette families used as semantic mapping sources. | open |
> `brand` and `neutral` are palette-layer conventions, not semantic roles \u2014 do not encode usage (`main`, `cta`, `danger`, `link`, `surface`, `focus`) in core names. `neutral` is functionally equivalent to "gray" in other systems.\n\n> **Why `CoreColorRef` is open.** It is typed as `'{core.colors.${string}}'` \u2014 a template literal, not a closed union derived from the concrete theme. Type safety for color usage lives at the _semantic_ layer (legal `ux \u00d7 role \u00d7 dimension \u00d7 state` and contrast pairings), not the palette-ref level. A closed union would break extensibility for derived themes and create a circular dependency between `Types.ts` and `baseTheme.ts`.
### Example (Core Color Definition)
```js
const coreColors = {
colors: {
brand: {
100: '#E6F0FF',
300: '#8CB8FF',
500: '#1463FF',
700: '#0B3EA8',
900: '#082861',
},
neutral: {
0: '#FFFFFF',
50: '#F8FAFC',
100: '#F1F5F9',
200: '#E2E8F0',
300: '#CBD5E1',
400: '#94A3B8',
500: '#64748B',
700: '#334155',
900: '#0F172A',
1000: '#020617',
},
red: {
100: '#FEE2E2',
300: '#FCA5A5',
500: '#EF4444',
600: '#DC2626', // filled negative surfaces: neutral.0 text at AA Normal
700: '#B91C1C',
900: '#7F1D1D',
},
green: {
100: '#DCFCE7',
300: '#86EFAC',
500: '#22C55E',
700: '#15803D',
900: '#14532D',
},
},
};
```
**Expected consumption pattern:** semantic color tokens reference core colors by alias.
---
## Semantic Colors
Semantic colors are the **public color API** — stable contracts that translate raw palettes into UI meaning along four axes: where in the experience (`ux`), what role (`role`), which visual layer (`dimension`), which state (`state`).
### Token structure
```text
{ux}.{role}.{dimension}.{state?}
```
See [Usage Examples](#usage-examples) below for concrete tokens.
---
## FSL Entity Kind Mapping
The `ux` axis is a projection-scoped subset of FSL Entity Kinds (FSL Structural Language §17.1). This table **mirrors** `ENTITY_TOKEN_MAPPING` in `@ttoss/fsl-ui` — the mapping is implemented and enforced by contract tests; the code is the single source of truth and wins on any divergence:
| FSL Entity Kind | Token `ux` | Notes |
| :-------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Action` | `action` | 1:1 |
| `Input` | `input` | 1:1 |
| `Selection` | `input` | checkbox, radio, picker — no separate `selection` UX context |
| `Navigation` | `navigation` | 1:1 |
| `Feedback` | `feedback` | 1:1 |
| `Collection` | `informational` | menu, list, table |
| `Overlay` | `informational` | dialog, popover |
| `Disclosure` | `navigation` | accordion, collapsible panel, `` — in-place reveal answers "what's here?" (structural orientation, ADR-001); uses `expanded` state for open/closed contract |
| `Structure` | `informational` | panel, shell, frame |
Interaction patterns that do not correspond to an Entity Kind (tooltips, helper banners, search/filter widgets) are expressed through existing kinds — typically `Overlay` for guidance and `Input` for discovery.
---
## Role Coverage
`role` is a **discriminated union** of two decision classes (see [FSL Lexicon §5](../../fsl/fsl-lexicon.md)) — a token carries one or the other, never both:
- **Emphasis**: `primary`, `secondary`, `accent`, `muted`
- **Valence**: `positive`, `caution`, `negative`
A valence implies its own emphasis. Intensity within a valence is expressed by `dimension` (e.g. `negative.background` is louder than `negative.text`), not by combining emphasis with valence. Each UX context enables only the subset that has stable meaning in it:
| Class | Role | `action` | `input` | `navigation` | `feedback` | `informational` |
| :------- | :---------- | :------: | :-----: | :----------: | :--------: | :-------------: |
| Emphasis | `primary` | ✓ | ✓ | ✓ | ✓ | ✓ |
| Emphasis | `secondary` | ✓ | ✓ | ✓ | — | ✓ |
| Emphasis | `accent` | ✓ | — | ✓ | ✓ | ✓ |
| Emphasis | `muted` | ✓ | ✓ | ✓ | ✓ | ✓ |
| Valence | `positive` | — | ✓ | — | ✓ | ✓ |
| Valence | `caution` | — | ✓ | — | ✓ | ✓ |
| Valence | `negative` | ✓ | ✓ | — | ✓ | ✓ |
**Why some cells are empty:**
- `action.positive / action.caution` — Outcome and risk live in `feedback.*`; an Action's own colour expresses only `negative` evaluation (FSL §5). Destructive consequence (FSL §6) is a frequent driver of that choice, but the two dimensions are distinct — `negative` may also encode adverse-but-non-destructive intent (cancel paid subscription).
- `navigation.*` valences — Navigation communicates location (`current`, `visited`), not health state.
- `feedback.secondary` — Feedback is direct: `primary`, `muted`, and `accent` cover its emphasis range. `feedback.accent` is the **informative** status ("in progress", "new", "info") — noteworthy but judgement-free, and the canonical fill for activity indicators (ProgressBar, Meter).
- `input.accent` — Inputs use `primary` for the brand-influenced active state; `accent` creates hierarchy ambiguity.
#### The Action emphasis ladder is one mechanism, not three
Within `action`, the three neutral rungs differ by **how much fill they carry**,
never by switching to a different device:
| Rung | Resting appearance |
| :---------- | :------------------------------------------------------------------------------------------------ |
| `primary` | Solid fill at the ramp's extreme (near-black in light, near-white in dark) |
| `secondary` | A light fill — visibly present, clearly below primary |
| `muted` | The **surface's own colour**, border included: no visible edge at rest, the fill appears on hover |
`muted` is the system's idiom for "no fill", and it is deliberately an opaque
surface-coloured token rather than `transparent`: every semantic background
stays a verifiable value, which is what lets the contrast guarantees
(ADR-015) be computed at all. Giving `muted` a visible border instead made it
read as the _outlined secondary_ of other design systems and inverted the
ladder's perceived order — the mistake the 2026-07-25 review corrected.
A role whose resting `(background, border, text)` triple duplicates another
role in the same context is a defect in any theme, and is enforced as such
(`colors.test.ts` → "roles within a context are distinguishable").
### Picking a role
Valence dominates emphasis: if the token communicates **outcome or validity** (success / warning / error / destructive), pick the valence first — emphasis is implicit. Otherwise pick the emphasis that matches **hierarchy weight in the current view**.
**Emphasis (no outcome to communicate):**
| You want to communicate… | Role |
| :------------------------------------------------------------------ | :---------- |
| the single most important element on this view | `primary` |
| an alternative coexisting with the primary one | `secondary` |
| a highlight that draws attention without being the main path | `accent` |
| presence with low priority (helper text, divider, optional control) | `muted` |
> Only one `primary` per view per `{ux}`. If two candidates compete for `primary`, one of them is `secondary`.
**Valence (outcome / validity to communicate):**
| The token reports… | Role |
| :---------------------------------------------------------------------------- | :----------------------- |
| success, completion, validity confirmed | `positive` |
| risk that needs attention but the user is not blocked | `caution` |
| failure, invalid state, or adverse intent (including destructive consequence) | `negative` |
| no outcome — just hierarchy | use **emphasis** instead |
> Intensity _within_ a valence is expressed by `dimension`, not by combining with emphasis.
>
> ❌ `feedback.negative.primary.background.default` — combining valence + emphasis is forbidden.
> ✅ `informational.negative.text.default` — quiet error (foreground only).
> ✅ `informational.negative.background.default` — loud error (filled surface).
**Where the loudness ladder does and does not exist.** The two rungs above are a
ladder only where the valence's `text` is a standalone ink. In `input` and
`informational` it is, and a part may read it while sitting on any surface — the
validation message is that case. In `action` and `feedback` the valence ships as
a **filled** surface, so `text` is the label _on that fill_ (near-white) and there
is no quiet rung inside those contexts: a destructive button is filled, a status
toast is filled — and it cannot be added by reaching for emphasis, which the ❌
above forbids. Both cases are instead expressed by
[cross-cutting](#cross-cutting-tokens-siblings-of-semanticcolors) inks, because
a part that paints the stratum's own colour needs an ink that is a system-wide
default no `{ux}` owns — the same shape as the focus ring, and the same §6
mechanism:
| The part… | Ink |
| :------------------------------------------------------------ | :------------------------------------- |
| **performs** a destructive act (a quiet "Delete") | `semantic.consequence.destructive.ink` |
| **reports** an outcome (a status mark, an error summary line) | `semantic.valence.{valence}.ink` |
The component layer scopes when each applies (`@ttoss/fsl-ui` CONTRACT §3.3).
---
## Dimension and State Registry
The foundation keeps a **small canonical registry**. `ux` is defined in [UX contexts](#ux-contexts-in-60-seconds); `role` in [Role Coverage](#role-coverage). Domain-specific semantics (`social`, `commerce`, `gamification`) do not belong to the foundation \u2014 model them at the pattern/application layer unless promoted through governance.
### Dimension level
| `dimension` | Meaning |
| :----------- | :--------------------------------------------------------- |
| `background` | fills and surface backgrounds |
| `border` | outlines, separators, rings, and other line-color pairings |
| `text` | readable foreground, labels, and text-like icons |
### State level
| `state` | Meaning |
| :-------------- | :--------------------------------------- |
| `default` | resting/base state |
| `hover` | pointer hover |
| `active` | press/engaged moment |
| `focused` | keyboard/programmatic focus |
| `disabled` | unavailable/non-interactive |
| `selected` | selected item in a set |
| `checked` | on/off control state |
| `pressed` | pressed toggle state |
| `expanded` | disclosure open state |
| `current` | current location in navigation |
| `visited` | visited link state |
| `indeterminate` | mixed/unknown boolean state |
| `droptarget` | valid drag-and-drop destination |
| `invalid` | failed runtime validation (`input` only) |
> Keep the state set stable.
> Add a new state only when the meaning cannot be expressed by an existing one.
#### Picking a state (disambiguation)
Several states sound interchangeable but answer different questions. Pick by **what the state asserts about the element**, not by the verb in the component name.
| The state asserts… | State |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- |
| pointer is currently over the element | `hover` |
| pointer/key is currently down on the element (transient, lasts only while held) | `active` |
| element has keyboard or programmatic focus | `focused` |
| element is non-interactive | `disabled` |
| element is **one of many** in a set and the user picked it (tab, list row, segment) | `selected` |
| element is a **two-state control** that is currently on (checkbox, radio, switch) | `checked` |
| element is a **toggle button** that is currently engaged (persistent, not transient) | `pressed` |
| disclosure / accordion / details is currently open | `expanded` |
| element is the user's **current location** in a navigation set (active route, current step) | `current` |
| link points to a URL the user has visited | `visited` |
| boolean control is in a mixed/unknown state (parent checkbox over partial children) | `indeterminate` |
| element is a **valid drop destination** during an active drag | `droptarget` |
| the control's **value failed runtime validation** (`isInvalid` — never authorial; the control keeps its authored role, the message carries `negative`; ADR-017) | `invalid` |
**Common confusions resolved:**
- **Tab in a tablist** → `selected` (one of many) and, when it represents the live route, also `current`. Not `active`, not `pressed`.
- **Filter chip / removable tag (`TagGroup`)** → `selected` (set membership — the user picked this one of many). Not `pressed`: a tag is not a toggle button. Removal is a separate close affordance (a remove button inside the tag), not a state.
- **Toggle button ("Bold" in a toolbar)** → `pressed` (persistent). `active` is the brief moment of clicking.
- **Checkbox / Switch / Radio** → `checked`. Not `selected`, not `pressed`.
- **Open accordion section** → `expanded`. Not `active`, not `selected`.
- **Currently viewed nav item** → `current`. Not `selected`, not `active`.
- **Button mid-click** → `active`. Releases back to `default` / `hover`.
---
## Legal Combinations
Not every `{ux} × role × state` is valid. Allowed **roles** per context are in [Role Coverage](#role-coverage); allowed **states** per context are below. Both are enforced by `Types.ts` — a token outside its row will not type-check.
### Legal states per context
Most contexts share an **interactive base**: `default`, `hover`, `active`, `focused`, `disabled`, `droptarget`. `feedback` is the exception — feedback is communicative, not interactive (FSL §3), so only `default`, `focused` (focusable wrapper / close button), and `disabled` apply.
| `ux` | Allowed states (full, no implicit base) |
| :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| `action` | `default`, `hover`, `active`, `focused`, `disabled`, `droptarget`, `pressed`, `expanded` |
| `input` | `default`, `hover`, `active`, `focused`, `disabled`, `droptarget`, `selected`, `checked`, `indeterminate`, `pressed`, `expanded`, `invalid` |
| `navigation` | `default`, `hover`, `active`, `focused`, `disabled`, `droptarget`, `selected`, `current`, `visited`, `expanded` |
| `feedback` | `default`, `focused`, `disabled` _(communicative, not interactive)_ |
| `informational` | `default`, `hover`, `active`, `focused`, `disabled`, `droptarget`, `selected`, `visited`, `expanded` |
### Dimension expectations
Not every implementation needs all three dimensions. Components choose which they consume.
| Pattern | Dimensions used |
| :------------- | :----------------------------- |
| Text link | `text` |
| Ghost button | `text`, `border` |
| Filled button | `background`, `text` |
| Surface / card | `background`, `border`, `text` |
---
## Relationship to Modes
Core palette values are **immutable across modes**; modes remap which core tokens the semantic layer references. Token names and component code never change — the remap doctrine lives in [Modes](../modes.md#relationship-to-the-token-model).
---
## Cross-cutting tokens (siblings of `semantic.colors.*`)
These tokens carry **system-wide defaults** that no `{ux}` owns. They live as siblings of `semantic.colors.*` per [model.md §6](../model.md#6-no-parallel-vocabulary), not inside it:
- `semantic.focus.ring.color` — system focus indicator color
- `semantic.overlay.scrim` — modal backdrop
- `semantic.overlay.outline` — boundary of a surface that **occludes** content
- `semantic.consequence.destructive.ink` — foreground for a destructive part that paints no surface
- `semantic.valence.{positive,caution,negative}.ink` — foreground for a part that **reports** that valence while painting no surface (ADR-029)
- `semantic.rail.track` — the unfilled part of a `ProgressBar`/`Meter`/`Slider` track; darkens in dark mode, unlike a border (ADR-028)
They are **not** parallel vocabulary: `{ux}.{role}.border.focused` answers _"what does this `{ux}`'s own edge become while focused?"_; `semantic.focus.ring.color` answers _"what marks focus?"_. Likewise `{ux}.{valence}.text` answers _"what is this `{ux}`'s valence ink on its own surfaces?"_; the valence inks answer _"what marks a part reporting that outcome while painting nothing?"_.
**Why `consequence.destructive.ink` and `valence.negative.ink` both exist.** They resolve to the same value in the base theme, by choice rather than by identity. [FSL Lexicon §10.5](../../fsl/fsl-lexicon.md) keeps `negative` (an Evaluation — what is being _reported_) apart from `destructive` (a Consequence — what an interaction _does_), so the two answer different questions and a theme may repoint one without the other: a product that wants "Delete" rows louder than error reports needs both addresses. Pick by asking whether the part reports an outcome or performs an act.
**No `primary`/`accent` valence ink.** `role` is a discriminated union of Emphasis and Valence (see [Role Coverage](#role-coverage)); an emphasis rung carries no outcome, so a valence ink has nothing to say there. A part on an emphasis rung takes the stratum's ordinary ink.
### Focus color — the ring indicates, the border tints
The two are **layers, not alternatives**, and every focusable component uses both.
**`semantic.focus.ring.color` is the indicator, on every entity alike.** It is drawn as an `outline` — never a `border`, which would shift layout — and floated off the control's edge, so the surface it must contrast against is the stratum behind the component rather than the component's own fill. That is what lets one system-wide colour serve everything: a filled `action.primary` pill is near-black in light and near-white in dark, and no single edge colour clears both it and the page, but a ring sitting outside it only ever meets the page.
**`{ux}.{role}.border.focused` re-tints the component's own edge underneath that ring.** It reinforces, and carries no indication duty of its own — which is why a filled surface may leave it below the border floor without the component becoming unfocusable.
One case inverts the emphasis: an `Input` carrying a validation valence keeps that valence in its border while focused (`input.{negative|caution}.border.focused`), because dropping it would make focusing an invalid field look like fixing it. The ring is unchanged — the valence rides the border, not the indicator.
> Contrast duty follows indication. The ring owes [Required pairing #3](#required-pairings) against every stratum it can land on; the tinted border owes the border pairing, and is exempt where it sits on its own role's fill.
### Example
A focusable profile card (no obvious `{ux}`):
- line geometry from `semantic.border.outline.surface` + `semantic.focus.ring.{width,style,offset}` on `:focus-visible`
- ring colour from `semantic.focus.ring.color`; the card has no `{ux}` edge to tint
A text input in error:
- line geometry from `semantic.border.outline.control` + `semantic.focus.ring.{width,style,offset}` on `:focus-visible`
- ring colour from `semantic.focus.ring.color`, as everywhere
- edge colour from `input.negative.border.focused` — the valence survives focus
A raised card may combine:
- surface color from `informational.primary.background.default`
- outline color from `informational.muted.border.default`
- shadow from `elevation.surface.raised`
### Stacking informational surfaces
Multiple `informational` surfaces commonly overlap in the visual hierarchy — a Dialog (`Overlay`) over a page, a Card (`Structure`) over a panel, a row inside a List (`Collection`). They share the same UX context by design (see [FSL Entity Kind Mapping](#fsl-entity-kind-mapping)) and may resolve to the **same** `informational.*.background` value, especially in dark modes where the available `core.colors.neutral` range is compressed.
Differentiation between stacked `informational` surfaces is paid in this order — **never in colour**:
1. **`elevation`** is the primary separator. `Overlay → elevation.surface.overlay`, `Structure`/`Collection` → `elevation.surface.flat | raised`. Drop shadows are local to each level, so the rule survives arbitrary nesting (Card inside Dialog inside Drawer): each level paints its own shadow over whatever sits beneath it.
2. **`border.outline.surface`** is the secondary separator. A 1px outline at ≥ 3:1 contrast against the adjacent background guarantees a perceptual edge even when shadow is suppressed (high-contrast preferences, print). **Which colour that outline takes depends on whether the surface occludes.** An _embedded_ surface (a card, a panel in the flow) draws `{ux}.{role}.border.default` — a deliberate hairline, listed in the border pairing's soft inventory, because losing its edge loses decoration. A surface that **covers** content draws `semantic.overlay.outline`, the cross-cutting boundary, because losing _its_ edge loses the information about where the covered content resumes. One token cannot be both, and the duty above belongs to the second.
3. **Tonal step displacement** is the optional reinforcement, delivered through `elevation.tonal.*` — **not** a second background token. By default the page and every contained `informational` surface resolve from the _same_ token (`informational.primary.background.default`); there is no separate `page` colour role, and none should be added. When a theme wants a raised surface to read as a literal step lighter/darker than the page (the classic "grey page, white cards", or dark-mode lifted surfaces), it maps `elevation.tonal.{raised,overlay,blocking}` to a surface-colour overlay on top of the shared background. The page (flat stratum) has no tonal overlay, so the net effective colours differ by one step while the base colour vocabulary stays single-sourced. This keeps [Rules of Engagement #4](#rules-of-engagement-non-negotiable) intact: the colour token is not carrying depth — `elevation` is.
> **Why not two background tokens.** Page-vs-card is a stratum distinction, and strata are an `elevation` axis, not a `role` axis (`role` is emphasis/valence, §Role Coverage). Splitting the page background into its own colour role would encode depth in colour — the exact move Rule #4 forbids. The single `informational.primary.background.default` + `elevation` (shadow) + `elevation.tonal` (surface lift) + `border.outline.surface` fully expresses the stack.
This is the operational form of [Rules of Engagement #4](#rules-of-engagement-non-negotiable): colour expresses intent, not depth. If two stacked surfaces still feel indistinguishable after applying (1) + (2) + (3), the answer is to strengthen elevation/border/tonal or remap a step — never to introduce a new colour bucket.
---
## Rules of Engagement (non-negotiable)
1. **Semantic-only consumption.** Components consume semantic colors only; core never directly.
2. **Intent, not appearance.** Names express role and meaning — forbid `buttonBlue`, `dangerBg`, `darkBorder`, `cardBorderSoft`, `textOnDark`. No component or mode names in foundation tokens.
3. **Keep the registry small.** Do not expand `ux`, `role`, or `state` casually; promote new entries only through governance.
4. **Color does not model depth.** Use `elevation` for depth, `borders` for line geometry; do not invent extra color roles to encode them.
5. **Validate pairings, not swatches.** A color is only valid when its intended `text ↔ background` or `border ↔ adjacent surface` pairing is valid.
---
## Usage Examples
| Usage | Token example |
| :------------------------------- | :------------------------------------- |
| Filled primary button background | `action.primary.background.default` |
| Filled primary button label | `action.primary.text.default` |
| Input border at rest | `input.primary.border.default` |
| Input border on focus | `input.primary.border.focused` |
| Current nav item text | `navigation.primary.text.current` |
| Muted body copy | `informational.muted.text.default` |
| Negative feedback surface | `feedback.negative.background.default` |
| Positive feedback text | `feedback.positive.text.default` |
### Example (Semantic Color Definition)
```js
const semanticColors = {
action: {
primary: {
background: {
default: '{core.colors.brand.500}',
hover: '{core.colors.brand.700}',
active: '{core.colors.brand.900}',
disabled: '{core.colors.neutral.200}',
},
text: {
default: '{core.colors.neutral.0}',
disabled: '{core.colors.neutral.500}',
},
border: {
default: '{core.colors.brand.500}',
focused: '{core.colors.brand.700}',
disabled: '{core.colors.neutral.200}',
},
},
},
informational: {
muted: {
text: {
default: '{core.colors.neutral.500}',
},
border: {
default: '{core.colors.neutral.200}',
},
},
},
feedback: {
negative: {
background: {
default: '{core.colors.red.100}',
},
text: {
default: '{core.colors.red.900}',
},
border: {
default: '{core.colors.red.500}',
},
},
},
};
```
---
## Theming
Themes tune **core palette values**, **which core tokens semantic tokens reference**, and **alternate semantic mappings per mode**. Semantic token names never change across themes. A theme becomes more muted, vivid, angular, enterprise, or playful by changing core values and semantic mappings — not by inventing parallel semantic vocabulary.
---
## Validation
### Errors (validation must fail when)
- a semantic color token uses an invalid `ux → role` combination
- a semantic color token uses a state outside the allowed state restrictions for that contract
- any required semantic pairing fails the contrast targets defined below
- any supported mode fails the same required pairings for the same semantic contract — an alternate mode remaps references by hand, so it is where a role's `background` subtree can move while its `border` subtree stays behind
- an alternate mode declares a semantic path the base does not — a mode remaps references ([model.md § Modes](../model.md#modes)), it never adds a leaf, because component bindings mirror the base shape and an alt-only leaf is unreachable: its value ships and nothing can read it
### Warning (validation should warn when)
- a separately defined state token resolves to the same color as the state it is meant to distinguish
- a separately defined `focused`, `selected`, or `current` token resolves to the same color as its default state
- two distinct semantic tokens in the same `ux` / `dimension` / `state` resolve to the same color
### Required pairings
Validation must check at least these pairings:
1. **Text pairing**
- `*.text.*` against the corresponding `*.background.*`
- normal text: `≥ 4.5:1`
- large text: `≥ 3:1`
- Only `*.muted.*` contexts (intentionally subdued) are held to the large-text
floor. All other contexts — including `action.*` button labels, which render
at `text.label` sizes and do **not** qualify as WCAG large text — must meet
`≥ 4.5:1`.
- **Corresponding is where the part renders, not who owns the token.** A part
that reads one role's ink and paints no surface of its own — the validation
message is the declared case — pairs against the surface it lands on. Because
the page and every contained surface share one background token and differ by
`elevation.tonal.*` ([Stacking informational surfaces](#stacking-informational-surfaces)),
"the surface it lands on" is every stratum, not one value.
- **A `background` state with no ink of its own still renders one.** The
component contract falls back to `text.default` (the selection mark resolves
`indeterminate → checked → default`), so validation pairs the **effective**
ink against every declared background state — never only the same-state
declarations. A same-state-only check audits a pair nobody renders and skips
the pair everyone does.
2. **Border / non-text pairing**
- `*.border.*` against the adjacent background it sits on
- minimum: `≥ 3:1`
- `disabled` is exempt (WCAG 2.2 §1.4.3), as it is for the text pairing.
- A border that resolves to its own background is a role with **no edge by
construction** — a distinct outcome from a soft edge, and validated as its
own set, so that a role gaining or losing its edge is a failure in either
direction.
3. **Focus pairing**
- the focused color against the adjacent background
- and, when focus distinction depends on color, against the prior unfocused state
- The focused colour is `semantic.focus.ring.color` — the indicator, not the tint ([the ring indicates, the border tints](#focus-color--the-ring-indicates-the-border-tints)). Because the ring is floated off the control, the adjacent background is every stratum it can land on, so this is a **cross-role** pairing and belongs with pairing #1's inventory rather than inside a `{ux}.{role}` subtree.
4. **Selected/current pairing**
- the selected or current color against the adjacent background
- and, when distinction depends on color, against the prior state
> Color tokens define the semantic contrast contract. Meaning that depends on more than color alone is validated at the pattern, component, and final output layers.
---
## Elevation
Elevation tokens define the **depth system** of ttoss.
Elevation is the perceived depth of a surface in the interface.
It is expressed through **surface level** and **shadow recipe** working together.
Elevation is used to:
- clarify spatial hierarchy
- separate surfaces from their surroundings
- communicate temporary lift or overlay behavior
- support focus through depth, not just through borders
It must be:
- **Structural** — depth should reflect interface hierarchy
- **Predictable** — surfaces at the same level should feel consistent
- **Controlled** — not every container needs elevation
- **Theme-aware** — depth must still read correctly in dark themes
> Key principle: **Elevation is depth, not shadow alone.**
This system is built on **two explicit layers**:
1. **Core Tokens** — shadow recipes
2. **Semantic Tokens** — stable surface depth contracts consumed by UI code
Components must always consume **semantic elevation tokens**, never core elevation recipes directly.
> **Rule:** Core elevation tokens are never referenced in components.
---
## Scope
Elevation defines **depth**.
It does **not** define:
- layering order (`z-index`)
- border emphasis
- visual meaning through color
- interaction states by itself
Use:
- **Elevation** for depth
- **Z-Index** for stacking order
- **Borders** for structural separation
- **Colors** for surface meaning
---
## Core Tokens
Core elevation tokens are shadow recipes.
They are intent-free and exist only to provide the physical shadow definitions used by semantic elevation tokens.
### Core ramps
Core elevation has two optional ramps. The levels below are the default reference implementation.
**`level` ramp** — standard-opacity recipes, used by default in light themes:
| Token | Default meaning |
| :----------------------- | :--------------------------------------------------------- |
| `core.elevation.level.0` | no elevation |
| `core.elevation.level.1` | subtle depth (not mapped to a semantic stratum by default) |
| `core.elevation.level.2` | default raised surface |
| `core.elevation.level.3` | strong overlay depth |
| `core.elevation.level.4` | highest application-controlled depth |
**`emphatic` ramp** (optional) — high-opacity recipes for surfaces needing stronger depth contrast (e.g., on dark or heavily-colored backgrounds). Mode-agnostic: expresses shadow weight, not a mode label. Themes include this ramp when a dark alternate requires higher-opacity recipes.
| Token | Default meaning |
| :-------------------------- | :---------------------------------------------------- |
| `core.elevation.emphatic.0` | no elevation |
| `core.elevation.emphatic.1` | subtle depth — higher opacity |
| `core.elevation.emphatic.2` | raised surface — higher opacity |
| `core.elevation.emphatic.3` | overlay depth — higher opacity |
| `core.elevation.emphatic.4` | highest application-controlled depth — higher opacity |
> Keep the number of levels small — elevation should remain easy to reason about.
> Every `{core.elevation.level.X}` or `{core.elevation.emphatic.X}` ref declared in semantic tokens must resolve to a defined key in the theme.
### Example
```js
const coreElevation = {
elevation: {
level: {
0: 'none',
1: '0 1px 2px rgba(0, 0, 0, 0.06), 0 1px 1px rgba(0, 0, 0, 0.04)',
2: '0 4px 8px rgba(0, 0, 0, 0.08), 0 2px 4px rgba(0, 0, 0, 0.06)',
3: '0 8px 16px rgba(0, 0, 0, 0.10), 0 4px 8px rgba(0, 0, 0, 0.08)',
4: '0 16px 32px rgba(0, 0, 0, 0.14), 0 8px 16px rgba(0, 0, 0, 0.10)',
},
// Optional — include when the theme supports a dark alternate
emphatic: {
0: 'none',
1: '0 1px 2px rgba(0, 0, 0, 0.20), 0 1px 1px rgba(0, 0, 0, 0.14)',
2: '0 4px 8px rgba(0, 0, 0, 0.24), 0 2px 4px rgba(0, 0, 0, 0.18)',
3: '0 8px 16px rgba(0, 0, 0, 0.28), 0 4px 8px rgba(0, 0, 0, 0.22)',
4: '0 16px 32px rgba(0, 0, 0, 0.34), 0 8px 16px rgba(0, 0, 0, 0.28)',
},
},
};
```
**Expected consumption pattern:** semantic elevation tokens reference core elevation recipes by alias.
---
## Semantic Tokens
Semantic elevation tokens define the **surface strata** of the interface.
They are intentionally anchored in **surface role**, not in component names.
### Token structure
```text
elevation.surface.{stratum}
```
### Canonical semantic set
`elevation.surface.*` defines shadow-based depth contracts:
- `elevation.surface.flat`
- `elevation.surface.raised`
- `elevation.surface.overlay`
- `elevation.surface.blocking`
`elevation.tonal.*` is an optional sibling for surface color overlays that pair with shadows to preserve depth in dark or heavily-colored themes. Omit when not needed.
> Keep the `surface.*` set stable. Do not create component-specific elevation tokens.
### Semantic Tokens Summary Table
| token | use when you are building… | contract (must be true) | default mapping |
| :--------------------------- | :------------------------------------------ | :--------------------------------------------- | :----------------------- |
| `elevation.surface.flat` | surfaces flush with the page | no perceived lift | `core.elevation.level.0` |
| `elevation.surface.raised` | cards, panels, raised surfaces | surface sits above the page but below overlays | `core.elevation.level.2` |
| `elevation.surface.overlay` | dropdowns, popovers, floating surfaces | surface floats above raised content | `core.elevation.level.3` |
| `elevation.surface.blocking` | dialogs, blocking sheets, blocking surfaces | highest surface depth in the normal app flow | `core.elevation.level.4` |
In a dark-mode alternate, `surface.*` tokens remap to `core.elevation.emphatic.*` recipes for proper contrast.
### Example
```js
const semanticElevation = {
elevation: {
surface: {
flat: '{core.elevation.level.0}',
raised: '{core.elevation.level.2}',
overlay: '{core.elevation.level.3}',
blocking: '{core.elevation.level.4}',
},
// Optional — include when the product uses tonal elevation overlays.
// Each token resolves to a color overlay (e.g., color-mix, rgba surface).
// tonal: {
// raised: '{core.colors.brand.50at8}',
// overlay: '{core.colors.brand.50at12}',
// blocking: '{core.colors.brand.50at16}',
// },
},
};
```
---
## Surface + Shadow
Elevation is not shadow alone.
A surface may also need a corresponding surface color treatment to preserve depth correctly, especially in dark themes.
This means:
- the **elevation token** defines the shadow recipe
- the **color system** defines the surface color at that depth
- components may need both to express depth correctly
> Shadows express lift.
> Surface color helps preserve that lift across themes.
---
## Rules of Engagement
1. **Semantic-only consumption**
Components use semantic elevation tokens only.
2. **Use elevation intentionally**
Do not add elevation when spacing or borders already solve the hierarchy.
3. **Elevation expresses depth, not stacking order**
Use z-index for layering order.
4. **Do not create component-specific elevation tokens by default**
Avoid `elevation.card`, `elevation.tooltip`, `elevation.toast`, etc.
5. **Keep states above the foundation layer**
Hover, pressed, and dragged behavior should usually be resolved in component or pattern logic, not by expanding the foundation prematurely.
6. **Validate in dark themes**
Shadows alone may not communicate depth well enough.
---
## Decision Matrix
1. **Should this surface feel flush with the page?**
→ `elevation.surface.flat`
2. **Should this surface feel gently lifted from the page?**
→ `elevation.surface.raised`
3. **Should this surface float above normal content?**
→ `elevation.surface.overlay`
4. **Should this surface dominate the normal application flow?**
→ `elevation.surface.blocking`
5. **Are you trying to show order, not depth?**
→ Use z-index instead
---
## Usage Examples
| Usage | Token |
| :---------------------------- | :--------------------------- |
| Page section or shell surface | `elevation.surface.flat` |
| Card or panel | `elevation.surface.raised` |
| Dropdown or popover | `elevation.surface.overlay` |
| Dialog or blocking sheet | `elevation.surface.blocking` |
> Build output may expose semantic elevation tokens as CSS variables or framework-specific bindings. The semantic names remain the API.
---
## Theming
Themes may tune:
- core shadow recipes
- semantic mappings if the product intentionally changes depth character
- paired surface colors in the color system
Semantic token names **never change across themes**.
---
## Validation
### Errors (validation must fail when)
- `elevation.surface.flat` resolves to a visible shadow recipe instead of no elevation
- any of these tokens resolves to `none`, `0`, or an equivalent non-visible shadow recipe:
- `elevation.surface.raised`
- `elevation.surface.overlay`
- `elevation.surface.blocking`
- semantic depth order breaks:
- `flat > raised`
- `raised > overlay`
- `overlay > blocking`
### Warning (validation should warn when)
- adjacent semantic strata resolve to the same effective elevation contract:
- `flat = raised`
- `raised = overlay`
- `overlay = blocking`
- adjacent `level` ramp entries resolve to the same effective shadow recipe
- adjacent `emphatic` ramp entries resolve to the same effective shadow recipe (when `emphatic` is defined)
---
## Summary
- Core elevation tokens define shadow recipes
- Semantic elevation tokens define surface depth strata
- Elevation is depth, not shadow alone
- Surface color and shadow may need to work together
- States like hover and drag usually stay above the foundation layer
- The system remains small, clear, and durable
---
## Motion
Motion tokens define the **transition behavior system** of ttoss: durations, easing curves, and a small set of semantic motion contracts.
Motion exists to:
- provide **feedback**
- clarify **state changes**
- preserve **continuity** between interface states
- add **emphasis** only when it improves understanding
Motion is **optional at the theme level**.
A theme may choose a more expressive motion language or an intentionally static one.
In both cases, the **semantic token names remain the same**.
Motion must be:
- **Purposeful** — never decorative by default
- **Fast** — frequent transitions should feel responsive
- **Predictable** — small, stable token sets are easier to use correctly
- **Accessible** — non-essential motion must respect reduced-motion preferences
- **Themeable** — a theme may reduce motion substantially or disable it by default without changing semantic names
> Key principle: **motion defines behavior semantics, not a guarantee of animation.**
This system is built on **two explicit layers**:
1. **Core Tokens** — intent-free durations and easing curves
2. **Semantic Tokens** — stable motion contracts consumed by UI code
Components must always consume **semantic motion tokens**, never core motion tokens directly.
> **Rule:** Core motion tokens are never referenced in components.
---
## Scope
Motion defines **transition behavior**.
It does **not** define:
- component APIs
- state logic
- rendering technology
- whether a component must animate in every theme
- cinematic choreography or marketing-style animation systems
Use motion tokens to express:
- immediate feedback
- entering and exiting transitions
- intentional emphasis
- optional decorative behavior
If a theme should be static, that is resolved through **theme mappings**, not by removing semantic tokens.
---
## Core Tokens
Core motion tokens define the physical primitives of motion.
### Durations
| Token | Value | Meaning |
| :-------------------------- | :------ | :------------------------------------- |
| `core.motion.duration.none` | `0ms` | no animation |
| `core.motion.duration.xs` | `50ms` | instant feedback |
| `core.motion.duration.sm` | `100ms` | quick micro-interactions |
| `core.motion.duration.md` | `200ms` | default UI transitions |
| `core.motion.duration.lg` | `300ms` | larger surface transitions |
| `core.motion.duration.xl` | `500ms` | rare, high-travel or decorative motion |
> Keep durations short.
> Most UI motion, when enabled, should stay in the `100–300ms` range.
### Easings
| Token | Value | Use |
| :---------------------------- | :----------------------------- | :----------------------------------- |
| `core.motion.easing.standard` | `cubic-bezier(0.4, 0, 0.2, 1)` | default in-place transitions |
| `core.motion.easing.enter` | `cubic-bezier(0, 0, 0.2, 1)` | elements entering into rest |
| `core.motion.easing.exit` | `cubic-bezier(0.4, 0, 1, 1)` | elements leaving away from rest |
| `core.motion.easing.linear` | `linear` | continuous or time-based motion only |
### Example
```js
const coreMotion = {
motion: {
duration: {
none: '0ms',
xs: '50ms',
sm: '100ms',
md: '200ms',
lg: '300ms',
xl: '500ms',
},
easing: {
standard: 'cubic-bezier(0.4, 0, 0.2, 1)',
enter: 'cubic-bezier(0, 0, 0.2, 1)',
exit: 'cubic-bezier(0.4, 0, 1, 1)',
linear: 'linear',
},
},
};
```
---
## Semantic Tokens
Semantic motion tokens define the **few recurring motion roles** the system needs.
They are intentionally small and recipe-based.
### Token structure
```text
motion.{role}
motion.transition.{phase}
```
### Canonical semantic set
- `motion.feedback`
- `motion.transition.enter`
- `motion.transition.exit`
- `motion.emphasis`
- `motion.decorative`
### Semantic Tokens Summary Table
| token | use when you are building… | contract (must be true) | default mapping |
| :------------------------ | :----------------------------------------------------- | :------------------------------------------------------------------------------------- | :-------------------------------------------------------- |
| `motion.feedback` | hover, press, toggle, small confirmation | immediate response; may be animated or instantaneous depending on theme | `core.motion.duration.sm` + `core.motion.easing.standard` |
| `motion.transition.enter` | surface entering, content revealing, overlay appearing | entering behavior; may animate or resolve instantly in static themes | `core.motion.duration.md` + `core.motion.easing.enter` |
| `motion.transition.exit` | surface leaving, content dismissing, overlay closing | exiting behavior; may animate or resolve instantly in static themes | `core.motion.duration.sm` + `core.motion.easing.exit` |
| `motion.emphasis` | drawing attention to a relevant change | stronger than ordinary feedback when motion is enabled; may reduce to minimal or none | `core.motion.duration.lg` + `core.motion.easing.standard` |
| `motion.decorative` | ambient or non-essential motion | always optional; never required for understanding; should be disabled in static themes | `core.motion.duration.xl` + `core.motion.easing.linear` |
### Example
```js
const semanticMotion = {
motion: {
feedback: {
duration: '{core.motion.duration.sm}',
easing: '{core.motion.easing.standard}',
},
transition: {
enter: {
duration: '{core.motion.duration.md}',
easing: '{core.motion.easing.enter}',
},
exit: {
duration: '{core.motion.duration.sm}',
easing: '{core.motion.easing.exit}',
},
},
emphasis: {
duration: '{core.motion.duration.lg}',
easing: '{core.motion.easing.standard}',
},
decorative: {
duration: '{core.motion.duration.xl}',
easing: '{core.motion.easing.linear}',
},
},
};
```
---
## Static Motion Profile
A theme may intentionally choose a **static motion profile**.
This is valid.
In a static theme:
- semantic motion token names remain unchanged
- semantic tokens still exist and remain the public API
- durations may resolve to `core.motion.duration.none`
- `motion.transition.enter` and `motion.transition.exit` may collapse to the same effective contract
- `motion.emphasis` may collapse to minimal or no motion
- `motion.decorative` should be disabled by default
This allows products to keep a stable semantic contract while adopting a more restrained motion posture.
### Example
```js
const staticMotionTheme = {
motion: {
feedback: {
duration: '{core.motion.duration.none}',
easing: '{core.motion.easing.standard}',
},
transition: {
enter: {
duration: '{core.motion.duration.none}',
easing: '{core.motion.easing.enter}',
},
exit: {
duration: '{core.motion.duration.none}',
easing: '{core.motion.easing.exit}',
},
},
emphasis: {
duration: '{core.motion.duration.none}',
easing: '{core.motion.easing.standard}',
},
decorative: {
duration: '{core.motion.duration.none}',
easing: '{core.motion.easing.linear}',
},
},
};
```
> A static theme disables motion through **mapping**, not by deleting semantic contracts.
---
## Reduced Motion
Reduced motion is part of the motion contract.
When a user requests reduced motion:
- **remove** decorative motion
- **reduce or replace** emphasis motion
- prefer **fade** over scale, pan, bounce, or depth-like movement
- keep essential feedback and transitions only when they remain helpful and minimal
### Practical rule
- `motion.feedback` → may remain, but should stay minimal
- `motion.transition.enter` / `exit` → may remain, but should simplify
- `motion.emphasis` → reduce, replace, or disable
- `motion.decorative` → disable by default
### Output Guidance (Web)
The following CSS example is specific to web output:
```css
@media (prefers-reduced-motion: reduce) {
.decorativeMotion {
animation: none;
}
.enterTransition,
.exitTransition,
.emphasisMotion {
transition-duration: 0ms;
}
}
```
> Reduced motion is not only “shorter animation”.
> It may require using a different kind of transition or no transition at all.
---
## Rules of Engagement (non-negotiable)
1. **Semantic-only consumption**
Components use semantic motion tokens only.
2. **Motion is optional at the theme level**
A theme may be expressive or static. Both are valid if semantic names remain stable.
3. **Keep motion short when motion is enabled**
Frequent UI motion should feel immediate, not cinematic.
4. **Enter and exit are semantic phases**
They describe behavior roles, not a guarantee that a theme must animate them differently.
5. **Decorative motion is always optional**
It must never be required for understanding or task completion.
6. **Respect reduced motion**
Remove, reduce, or replace non-essential motion when requested.
7. **Do not create component-specific motion tokens by default**
Avoid `motion.modal`, `motion.drawer`, `motion.tooltip`, etc.
---
## Decision Matrix
1. **Is this a small immediate reaction to user input?**
→ `motion.feedback`
2. **Is something entering the interface?**
→ `motion.transition.enter`
3. **Is something leaving the interface?**
→ `motion.transition.exit`
4. **Are you intentionally drawing attention to a relevant change?**
→ `motion.emphasis`
5. **Is this ambient or non-essential motion?**
→ `motion.decorative`
6. **Should this theme be intentionally static?**
→ keep the same semantic tokens and remap them to `core.motion.duration.none`
---
## Usage Examples
| Usage | Token |
| :---------------------------------- | :------------------------ |
| Button hover / press | `motion.feedback` |
| Dialog or popover opening | `motion.transition.enter` |
| Dialog or popover closing | `motion.transition.exit` |
| Brief highlight to direct attention | `motion.emphasis` |
| Background shimmer / ambient loop | `motion.decorative` |
> Build output may expose semantic motion tokens as CSS variables or framework-specific bindings. The semantic names remain the API.
---
## Theming
Themes may tune:
- core durations
- core easing curves
- semantic mappings
- overall motion posture, including an intentionally static profile
Semantic token names **never change across themes**.
A theme may become more expressive, more restrained, or effectively static by changing core values and semantic mappings — not by inventing a parallel semantic vocabulary.
---
## Validation
### Errors (validation must fail when)
- core duration order breaks:
- `none > xs`
- `xs > sm`
- `sm > md`
- `md > lg`
- `lg > xl`
- generated output changes semantic token names or invents new motion semantics
- generated output does not emit reduced-motion overrides for motion tokens when the theme contains non-zero motion contracts
- generated output leaves `motion.decorative` enabled under reduced motion when the theme contains non-zero motion contracts
### Warning (validation should warn when)
- adjacent core duration steps resolve to the same effective value
- `motion.transition.enter` and `motion.transition.exit` resolve to the same effective easing contract in a non-static theme
- `motion.feedback` and `motion.transition.enter` resolve to the same effective motion contract in a non-static theme
- `motion.emphasis` resolves to the same effective motion contract as `motion.transition.enter` in a non-static theme
- reduced-motion output leaves `motion.transition.enter` and `motion.transition.exit` unchanged in a non-static theme
### Note
A theme with effectively no motion is valid.
Validation must not treat zero-motion semantic mappings as an error by themselves.
What matters is that:
- semantic token names remain stable
- the mappings are intentional
- reduced-motion output does not reintroduce non-essential motion
- the build preserves the contract
---
## Summary
- Core motion tokens define durations and easing curves
- Semantic motion tokens define a small set of reusable behavior contracts
- Motion is optional at the theme level
- Static themes remain valid when semantic names stay stable
- Reduced motion is part of the contract, not an afterthought
- Decorative motion is always optional
- The system stays small, predictable, and safe to evolve
---
## Opacity
Opacity tokens define the **transparency system** of ttoss.
Opacity is a visual modifier.
It does not carry UI meaning by itself.
Opacity should be used sparingly and only in cases where transparency is the correct mechanism, such as:
- scrims and backdrops
- loading veils
- controlled media dimming
It must be:
- **Restricted** — small and intentionally limited
- **Predictable** — avoid hidden side effects
- **Accessible** — never reduce critical contrast carelessly
- **Separate from color meaning** — most semantic meaning belongs to the color system
> Key principle: **Opacity is a modifier, not a primary semantic language.**
This system is built on **two explicit layers**:
1. **Core Tokens** — intent-free opacity values
2. **Semantic Tokens** — stable transparency contracts consumed by UI code
Components must always consume **semantic opacity tokens**, never core opacity tokens directly.
> **Rule:** Core opacity tokens are never referenced in components.
---
## Scope: Opacity vs Alpha Color
Opacity and alpha color are not the same thing.
- **Opacity** affects the entire element, including its contents.
- **Alpha color** affects only the specific color channel where it is applied.
This means:
- use **opacity tokens** for scrims, veils, and controlled whole-element dimming
- use **semantic color tokens with alpha** when only background, text, or borders should become transparent
> If the intention is “only the background should be translucent”, opacity is usually the wrong tool.
---
## Core Tokens
Core opacity tokens are intent-free numeric values.
They define the allowed transparency steps of the system.
### Core set
| Token | Value | Meaning |
| :----------------- | :----- | :---------------- |
| `core.opacity.0` | `0` | fully transparent |
| `core.opacity.25` | `0.25` | light dimming |
| `core.opacity.50` | `0.5` | medium dimming |
| `core.opacity.75` | `0.75` | strong dimming |
| `core.opacity.100` | `1` | fully opaque |
> Keep the scale small. Opacity becomes harder to reason about when too many intermediate values exist.
### Example
```js
const coreOpacity = {
opacity: {
0: 0,
25: 0.25,
50: 0.5,
75: 0.75,
100: 1,
},
};
```
**Expected consumption pattern:** semantic opacity tokens reference core opacity tokens by alias.
---
## Semantic Tokens
Semantic opacity tokens define the **few cases where transparency is a stable, reusable contract**.
Opacity semantics should remain intentionally small.
### Token structure
```text id="y7v9s9"
opacity.{role}
```
### Canonical semantic set
- `opacity.scrim`
- `opacity.loading`
- `opacity.disabled`
> Keep this set stable.
> Do not use opacity tokens as a generic replacement for semantic color or state tokens.
### Semantic Tokens Summary Table
| token | use when you are building… | contract (must be true) | default mapping |
| :----------------- | :------------------------------------------ | :------------------------------------------------ | :---------------- |
| `opacity.scrim` | modal backdrops, blocking dim layers | dims content behind a foreground layer | `core.opacity.50` |
| `opacity.loading` | loading veils over content or media | content remains visible but clearly de-emphasized | `core.opacity.50` |
| `opacity.disabled` | disabled visual media or image-like content | whole visual asset may be dimmed safely | `core.opacity.50` |
### Example
```js id="2r1vph"
const semanticOpacity = {
opacity: {
scrim: '{core.opacity.50}',
loading: '{core.opacity.50}',
disabled: '{core.opacity.50}',
},
};
```
---
## What Opacity Should Not Do
Opacity should **not** be the default mechanism for:
- text hierarchy
- icon emphasis
- focus indicators
- borders
- selected state
- error/success/warning meaning
- hiding interactive elements
Those concerns should usually be solved by:
- semantic color tokens
- border/focus tokens
- visibility/display/state logic
> Most state meaning belongs to the color system, not to opacity.
## Rules of Engagement (non-negotiable)
1. **Semantic-only consumption**
Components use semantic opacity tokens only.
2. **Do not use opacity for text or critical foreground by default**
Use semantic colors with alpha when needed.
3. **Do not use opacity as a hiding strategy**
`opacity: 0` does not remove interaction, focus, or DOM presence.
4. **Avoid stacking opacities**
Nested opacity compounds visually and becomes hard to predict.
5. **Use opacity only where whole-element dimming is intended**
If only one visual layer should become translucent, use alpha color instead.
6. **Remember layering side effects**
`opacity < 1` creates a stacking context.
## Decision Matrix (pick fast)
1. **Do you want to dim everything inside the element?**
→ Use an opacity token
2. **Do you want only the background or line color to be translucent?**
→ Use a semantic color token with alpha
3. **Are you trying to communicate UI state or emphasis?**
→ Use the color system first
4. **Are you trying to hide something?**
→ Do not use opacity alone
---
## Usage Examples
| Usage | Token |
| :-------------------------------------- | :----------------- |
| Modal backdrop | `opacity.scrim` |
| Loading veil over a card or media block | `opacity.loading` |
| Disabled avatar or image-like element | `opacity.disabled` |
### Example
```css id="0hqlsr"
.modalBackdrop {
opacity: var(--token-opacity-scrim);
}
.loadingVeil {
opacity: var(--token-opacity-loading);
}
```
> Build output may expose semantic opacity tokens as CSS variables or framework-specific bindings. The semantic names remain the API.
---
## Accessibility and Interaction Notes
Opacity affects the whole rendered element.
That means:
- it can reduce contrast unexpectedly
- it can dim text and controls unintentionally
- invisible elements may still be interactive if only opacity is changed
- reduced opacity may affect stacking by creating a new stacking context
Use opacity carefully, and always validate:
- readability
- focus behavior
- pointer behavior
- layering behavior
---
## Theming
Themes may tune:
- the core opacity values
- the mapping of `opacity.scrim`, `opacity.loading`, and `opacity.disabled`
Semantic token names **never change across themes**.
---
## Validation
### Errors (validation must fail when)
- core opacity order breaks:
- `0 > 25`
- `25 > 50`
- `50 > 75`
- `75 > 100`
- any semantic opacity token resolves outside the valid opacity range:
- less than `0`
- greater than `1`
- any of these tokens resolves to `0`, `1`, or an equivalent non-translucent value:
- `opacity.scrim`
- `opacity.loading`
- `opacity.disabled`
### Warning (validation should warn when)
- adjacent core opacity steps resolve to the same effective value
---
## Summary
- Opacity is a **restricted modifier**, not a broad semantic state system
- Core tokens define a small transparency scale
- Semantic tokens stay intentionally minimal
- Use opacity for scrims, loading veils, and controlled media dimming
- Use semantic colors instead when only one visual layer should be transparent
- Keep the family small, explicit, and hard to misuse
---
## Radii
Radii tokens define the **corner curvature system** of ttoss.
Radii shape the visual character of the interface. They influence:
- **Softness vs sharpness** — how angular or rounded the UI feels
- **Containment** — how clearly a surface feels bounded
- **Affordance** — how interactive elements communicate touchability
- **Consistency** — how shape stays coherent across the product
This system is built on **two explicit layers**:
1. **Core Tokens** — intent-free radius primitives
2. **Semantic Tokens** — stable shape contracts consumed by UI code
Components must always consume **semantic radii**, never core radii directly.
> **Rule:** Core radii are never referenced in components.
---
## Core Tokens
Core radii tokens are intent-free primitives.
They define the available degrees of corner curvature in the system.
Unlike spacing or typography, radii do **not** need a responsive engine.
Radii are usually stable across viewport sizes and should remain visually consistent unless a theme intentionally redefines them.
Radii are intentionally stable. Unlike spacing or typography, they do not require a responsive engine by default.
If a product needs adaptive curvature, it should be handled at the theme or pattern layer, not in the foundational token contract.
### Core set
- `core.radii.none`
- `core.radii.sm`
- `core.radii.md`
- `core.radii.lg`
- `core.radii.xl`
- `core.radii.full`
> Keep the scale small and opinionated. Too many radius steps weaken visual identity.
### Core Token Summary Table
| token | meaning | recommended use |
| :---------------- | :------------------ | :-------------------------------------------------------------------------- |
| `core.radii.none` | no rounding | square shapes, separators, intentionally angular UI |
| `core.radii.sm` | subtle rounding | compact controls, small details |
| `core.radii.md` | default rounding | standard controls and common surfaces |
| `core.radii.lg` | strong rounding | prominent surfaces and larger UI containers |
| `core.radii.xl` | expressive rounding | highly softened surfaces or brand-forward containers |
| `core.radii.full` | fully rounded | pills, capsules, and shapes whose intended form is explicitly fully rounded |
> `core.radii.full` expresses the intent of full roundness. Perfect circles still depend on the element's dimensions.
### Example
```js
const coreRadii = {
radii: {
none: '0px',
sm: '4px',
md: '8px',
lg: '12px',
xl: '16px',
full: '9999px',
},
};
```
**Expected consumption pattern:** semantic radii reference core tokens by alias.
---
## Semantic Tokens
Semantic radii are anchored in **shape contracts**, not component names.
The semantic set is intentionally **small and stable**.
Its job is to express the structural role of curvature in the interface without turning into component-specific aliases.
### Token structure
```text
radii.{contract}
```
### Semantic contracts
| `contract` | meaning |
| :--------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action` | Radius for the **command** silhouette — the CTA; pill in the base theme. Utility triggers (icon buttons, toggle buttons) are not commands and keep `control` (fsl-ui ADR-021 silhouettes) |
| `control` | Radius for interactive controls and touchable UI elements — fields, choice controls, utility triggers |
| `surface` | Radius for surfaces that contain or group content |
| `round` | Full-round shape intent for pills, capsules, and circular affordances |
Which components wear which silhouette is the consumer's decision (fsl-ui `tokens/CONTRACT.md` §1): in fsl-ui, `Button` wears `action`; `ActionButton` and `ToggleButton` wear `control`.
### Canonical semantic set
- `radii.action`
- `radii.control`
- `radii.surface`
- `radii.round`
> Keep this set stable. Do not add component-specific radii tokens by default.
### Semantic Tokens Summary Table
| token | use when you are building… | contract (must be true) | default mapping |
| :-------------- | :-------------------------------------------------------------------------- | :---------------------------------------------- | :---------------- |
| `radii.action` | command triggers — the CTA silhouette | the element is a command the user commits with | `core.radii.full` |
| `radii.control` | inputs, toggles, utility triggers, interactive chips, clickable affordances | the element is primarily an interactive control | `core.radii.md` |
| `radii.surface` | cards, panels, dialogs, menus, popovers, grouped containers | the element is primarily a containing surface | `core.radii.lg` |
| `radii.round` | pills, capsules, circular affordances, fully rounded shapes | the intended shape is explicitly fully rounded | `core.radii.full` |
### Example
```js
const semanticRadii = {
radii: {
action: '{core.radii.full}',
control: '{core.radii.md}',
surface: '{core.radii.lg}',
round: '{core.radii.full}',
},
};
```
---
## Scope: Tokens vs Components vs CSS Overrides
Radii tokens define **shape contracts**. They do not define component variants.
- **Design tokens** define the radius scale and the stable semantic contracts.
- **Components** consume those contracts (`radii.action`, `radii.control`, `radii.surface`, `radii.round`).
- **Component-specific corner rules** belong to the component or pattern layer, not the foundation layer.
> Example: an avatar does not need a dedicated `radii.avatar` token.
> If its intended shape is fully rounded, it consumes `radii.round`.
---
## Rules of Engagement (non-negotiable)
1. **Semantic-only consumption:** components use semantic radii only.
2. **Uniform-radius first:** radii tokens define one radius value per token.
3. **No component-specific radii tokens by default:** avoid `radii.avatar`, `radii.toast`, `radii.card`, etc.
4. **Round is an intent, not a component:** use `radii.round` whenever the intended shape is fully rounded.
5. **Theme the core, not the semantics:** brands may make the system more angular or softer by changing core values, never by renaming semantic tokens.
---
## Decision Matrix (pick fast)
1. **Is the element a command trigger (the "press me" silhouette)?**
→ `radii.action`
2. **Is the element primarily an interactive control (field, choice control, utility trigger)?**
→ `radii.control`
3. **Is the element primarily a containing surface?**
→ `radii.surface`
4. **Is the intended shape explicitly fully rounded?**
→ `radii.round`
---
## Advanced CSS Capabilities (escape hatches, not token contracts)
CSS supports more complex corner behavior than the ttoss radii foundation exposes by default, including:
- multiple radius values
- elliptical radii
- logical corner radius properties
These are **valid CSS capabilities**, but they are **not part of the canonical token contract**.
Use them only when layout or internationalization truly requires them.
### Examples of non-token escape hatches
- `border-radius: 8px 24px`
- `border-radius: 16px / 8px`
- `border-start-start-radius`
- `border-start-end-radius`
- `border-end-start-radius`
- `border-end-end-radius`
> If a pattern repeatedly needs corner-specific or logical-corner radii, that should be solved at the pattern/component layer first — not by expanding the foundation tokens prematurely.
---
## Usage Examples
| Usage | Token |
| :------------------------------------- | :-------------- |
| Command trigger (Button / CTA) radius | `radii.action` |
| Input or utility trigger radius | `radii.control` |
| Card or panel radius | `radii.surface` |
| Fully rounded chip or pill | `radii.round` |
| Avatar with fully rounded shape intent | `radii.round` |
> Build output may expose semantic radii as CSS variables or framework-specific bindings. The semantic names remain the API.
---
## Theming
Themes may tune:
- the **core radius scale** (`core.radii.sm`, `core.radii.md`, `core.radii.lg`, etc.)
- the semantic mappings (`radii.control`, `radii.surface`) if a brand intentionally changes the overall shape language
Semantic token names **never change across themes**.
---
## Validation
### Errors (validation must fail when)
- core radii order breaks:
- `none > sm`
- `sm > md`
- `md > lg`
- `lg > xl`
- `xl > full`
- `core.radii.full` resolves to `0`, `none`, or an equivalent non-visible radius
### Warning (validation should warn when)
- adjacent core radii steps resolve to the same effective value
- `radii.surface` resolves to a smaller effective radius than `radii.control`
---
## Summary
- Core radii define the available degrees of curvature
- Semantic radii define a small set of stable shape contracts
- Components consume only semantic radii
- Radii is **uniform-radius first**
- Corner-specific and logical-corner radii are **escape hatches**, not canonical tokens
- The system stays small, predictable, and scalable
---
## Sizing
Sizing tokens define the **physical bounds** of UI: widths, heights, and min/max constraints used to build interfaces that are consistent, accessible, and **natively responsive**.
This system is built on two explicit layers:
1. **Core Tokens** — intent-free primitives and the **responsive engine**
2. **Semantic Tokens** — sizing contracts consumed by UI code
> **Rule:** Core tokens are never referenced in components.
---
## Core Tokens
Core sizing tokens are **intent-free primitives** and the **single source of truth** for responsiveness.
They exist to:
- centralize fluid logic (all `clamp()` formulas live here)
- keep semantic tokens as **aliases** (stable names, theme-tunable engine)
- make the system predictable (no ad-hoc coefficients in semantics)
**Core tokens are never consumed by components.** Components consume semantic tokens only.
### Output Guidance (Web)
The following is specific to CSS/web output and does not affect the semantic contract.
1. A query container rule for layout surfaces:
```css
.tt-container {
container-type: inline-size;
}
```
2. A robust fallback strategy in build output:
- emit a viewport-safe fallback first
- override with container units when supported
```css
@supports (width: 1cqi) {
/* container-based overrides */
}
```
3. The core token set below (ramps + primitives).
### Core groups
#### 1) Fluid ramps (required)
Ramps are the **engine**. They are bounded ranges expressed with `clamp(min, preferred, max)`.
- `core.sizing.ramp.ui.1..8` — small→medium objects such as icons and identity
- `core.sizing.ramp.layout.1..6` — medium→large structural bounds such as surfaces
> Rule: semantic fluid tokens (`icon.*`, `identity.*`, `surface.maxWidth`) should map to ramp steps, not define new formulas.
#### 2) Primitives (required)
- `core.sizing.relative.em = 1em`
- `core.sizing.relative.rem = 1rem`
- `core.sizing.behavior.auto = auto`
- `core.sizing.behavior.full = 100%`
- `core.sizing.behavior.fit = fit-content`
- `core.sizing.behavior.min = min-content`
- `core.sizing.behavior.max = max-content`
- `core.sizing.viewport.height.full = 100dvh`
- `core.sizing.viewport.width.full = 100dvw`
#### 3) Ergonomic hit primitives (required)
- `core.sizing.hit.fine` — the single ergonomic floor for fine pointer (mouse, trackpad); may be fluid via `clamp(floor, preferred, max)` where `floor` is a fixed px minimum
- `core.sizing.hit.coarse` — the single fixed px floor for coarse pointer (touch); never fluid
`hit` is **one value per pointer profile**, not a scale — the theme's single ergonomic minimum for an interactive target (ADR-020). **Coarse** is **always fixed px** — reliable ergonomic guarantees for touch. **Fine** may use `clamp(floor, preferred, max)` where `floor` is a fixed px ergonomic minimum, so the `rem` `preferred` respects user font-size while accessibility is always guaranteed. The build output emits the fine value as the baseline and the coarse value inside `@media (any-pointer: coarse)` automatically.
### Example
```js
const coreSizing = {
sizing: {
ramp: {
ui: {
1: 'clamp(12px, calc(0.6cqi + 10px), 16px)',
2: 'clamp(14px, calc(0.8cqi + 11px), 20px)',
3: 'clamp(16px, calc(1.0cqi + 12px), 24px)',
4: 'clamp(20px, calc(1.2cqi + 14px), 32px)',
5: 'clamp(24px, calc(1.5cqi + 16px), 40px)',
6: 'clamp(32px, calc(1.8cqi + 20px), 56px)',
7: 'clamp(40px, calc(2.2cqi + 24px), 72px)',
8: 'clamp(48px, calc(2.6cqi + 28px), 96px)',
},
layout: {
1: 'clamp(320px, 40cqi, 480px)',
2: 'clamp(384px, 50cqi, 640px)',
3: 'clamp(480px, 60cqi, 800px)',
4: 'clamp(560px, 70cqi, 960px)',
5: 'clamp(640px, 80cqi, 1120px)',
6: 'clamp(768px, 90cqi, 1280px)',
},
},
relative: {
em: '1em',
rem: '1rem',
},
behavior: {
auto: 'auto',
full: '100%',
fit: 'fit-content',
min: 'min-content',
max: 'max-content',
},
viewport: {
height: {
full: '100dvh',
},
width: {
full: '100dvw',
},
},
hit: {
// A single ergonomic floor per pointer profile (ADR-020).
// Fine: clamp(floor, preferred, max) — floor is fixed px; preferred scales
// with rem (not cqi), so a control's height never grows with the window.
// Tuned desktop-first at 32px (GitHub/Linear ~32, Stripe ~36).
fine: 'clamp(32px, 2rem, 36px)',
// Coarse: always fixed px — touch ergonomics require a predictable,
// reliable target. 48px sits above the 44px Apple HIG floor.
coarse: '48px',
},
},
};
```
**Expected consumption pattern:** semantic tokens reference core tokens by alias.
Example: `icon.md → core.sizing.ramp.ui.3`, `surface.maxWidth → core.sizing.ramp.layout.5`.
## Semantic Tokens
Sizing semantics are anchored in **geometry and ergonomics**, not UX categories.
This avoids ambiguity and prevents token-per-component drift.
### Token structure
```text
{family}.{stepOrProperty}
```
- `family`: what kind of physical sizing contract this is
- `stepOrProperty`: the specific step or property inside that family
#### Families
| `{family}` | Description |
| :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hit` | the single minimum **interactive target** floor (ergonomic contract). One value per pointer profile; adapts to input capability. Fine may be fluid with `clamp()` (floor must be fixed px). Coarse is always fixed px. |
| `icon` | **visual glyph** sizing only. May be fluid via core ramp. |
| `identity` | **visual identity object** sizing (profile / brand / entity). May be fluid via core ramp. |
| `measure` | **readability measure** (line-length contract, character-based). |
| `surface` | **structural bounds** for UI surfaces (constraints, not components). |
| viewport | viewport primitives for full-height and full-width layouts. |
#### Canonical shapes
- `hit`
- `icon.{text|sm|md|lg}`
- `identity.{sm|md|lg|xl}`
- `measure.reading`
- `surface.maxWidth`
- `surface.card`
- `viewport.height.full`
- `viewport.width.full`
### Semantic Tokens Summary Table
| token | use when you are building… | contract (must be true) | default value |
| :--------------------- | :------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | :--------------------------------- |
| `hit` | any interactive target (buttons, inputs, toggles, list rows) | minimum interactive area; **not visual size**; **must not shrink**; enforce via `min-*` | theme-defined ergonomic floor |
| `icon.text` | glyph on the same line as text (button icon, picker chevron) | visual only; relative (`1em`) so the ink lands inside the cap-height band | `core.sizing.relative.em` |
| `icon.sm` | small glyphs / dense UI | visual only; bounded range via core ramp | `core.sizing.ramp.ui.2` |
| `icon.md` | standard icons | visual only; bounded range via core ramp | `core.sizing.ramp.ui.3` |
| `icon.lg` | prominent icons | visual only; bounded range via core ramp | `core.sizing.ramp.ui.4` |
| `identity.sm` | compact identity objects | visual only; bounded range via core ramp | `core.sizing.ramp.ui.5` |
| `identity.md` | standard identity objects | visual only; bounded range via core ramp | `core.sizing.ramp.ui.6` |
| `identity.lg` | prominent identity objects | visual only; bounded range via core ramp | `core.sizing.ramp.ui.7` |
| `identity.xl` | hero identity / brand objects | visual only; bounded range via core ramp | `core.sizing.ramp.ui.8` |
| `measure.reading` | long-form text containers | single bounded readability contract | `clamp(45ch, 60ch, 75ch)` |
| `surface.maxWidth` | page shells, content columns, card / panel / dialog wrappers | bounded structural max width; container-first | `core.sizing.ramp.layout.5` |
| `surface.card` | narrow standalone centered card (auth form, confirmation page) | bounded structural max width; distinct from `maxWidth` (page-shell cap) and `measure.reading` (line-length contract) | `core.sizing.ramp.layout.1` |
| `viewport.height.full` | full-height layouts | must use dynamic viewport units; use intentionally for full-height layouts | `core.sizing.viewport.height.full` |
| `viewport.width.full` | full-width layouts | must use dynamic viewport units; use intentionally for full-width layouts | `core.sizing.viewport.width.full` |
Accessibility note: WCAG 2.2 Target Size (Minimum) defines a lower baseline of `24×24` CSS px, with exceptions. ttoss recommends stronger ergonomic baselines, especially for coarse pointer environments, while allowing themes to tune values based on product needs.
### Hit target adaptation
`hit` defines an ergonomic contract, not a fixed pixel value.
Implementations should adapt hit targets based on input capability:
- **fine pointer** (`mouse`, `trackpad`) → more compact targets
- **coarse pointer** (`touch`) → larger targets
The build output handles this automatically. Fine values are emitted as the baseline; coarse values are injected based on input capability detection.
#### Output Guidance (Web)
In CSS output, the fine value is the baseline and the coarse value is injected inside `@media (any-pointer: coarse)`:
```css
:root {
--tt-sizing-hit: clamp(
32px,
2rem,
36px
); /* fine baseline — fluid via rem, ergonomic floor guaranteed */
}
@media (any-pointer: coarse) {
:root {
--tt-sizing-hit: 48px; /* touch override — fixed px, always reliable */
}
}
```
> The semantic token remains stable (`hit`).
> The runtime adapts the value.
Control geometry adapts to **user font (`rem`)** — never to the container
(`cqi`), which is reserved for _layout_ spacing/sizing — so a control's height
never grows just because the window is wider. See ADR-020.
## Rules of Engagement (non-negotiable)
1. **Hit vs visual:** never use `icon.*` or `identity.*` as hit targets; always enforce `hit` via `min-width` / `min-height`.
2. **Reading vs surface:** use `measure.reading` for long text; use `surface.maxWidth` for structural wrappers.
3. **No responsive logic in components:** responsiveness lives in Core (ramps + container units), not in component code.
4. **Dynamic dimensions:** avoid `100vh` and `100vw`; use `viewport.height.full` and `viewport.width.full`.
## Theming
Themes may tune:
- the **core ramps** (`core.sizing.ramp.ui.*`, `core.sizing.ramp.layout.*`)
- `surface.maxWidth` mapping to a different layout ramp step
- `measure.reading` in rare cases, validated with real content
- `core.sizing.hit.fine` to tune the ergonomic floor for mouse; may use `clamp(floor, preferred, max)` where `floor` is fixed px
- `core.sizing.hit.coarse` to adjust the ergonomic floor for touch; always fixed px
Semantic token names **never change across themes**.
---
## Validation
### Errors (validation must fail when)
- `hit.coarse` resolves to a fluid or intrinsic value, including `clamp(...)`, `cqi`, `%`, `auto`, or content-sizing keywords
- `hit.fine` uses `clamp()` without a fixed px floor (the minimum bound must be a literal `Npx` value, not a variable or formula)
- the coarse-pointer hit floor is smaller than the fine-pointer floor:
- `coarse < fine` (compare coarse fixed px to fine clamp floor)
- `measure.reading` is not a bounded character-based measure
- generated output does not emit fine-pointer hit values as the baseline and coarse-pointer hit values inside `@media (any-pointer: coarse)`
- generated output does not emit a viewport-safe fallback before container-based overrides
- generated output does not gate container-based overrides behind `@supports (width: 1cqi)`
- generated output emits `viewport.height.full` as `vh` instead of dynamic viewport units
- generated output emits `viewport.width.full` as `vw` instead of dynamic viewport units
### Warning (validation should warn when)
- any `icon.*` token resolves outside `core.sizing.ramp.ui.*`
- any `identity.*` token resolves outside `core.sizing.ramp.ui.*`
- `surface.maxWidth` resolves outside `core.sizing.ramp.layout.*`
- `viewport.height.full` does not resolve to `core.sizing.viewport.height.full`
- `viewport.width.full` does not resolve to `core.sizing.viewport.width.full`
- a resolved `hit` value (fine or coarse) is below `24px`
- adjacent `icon.*` tokens resolve to the same effective value
- adjacent `identity.*` tokens resolve to the same effective value
- the fine-pointer and coarse-pointer hit floors resolve to the same value
- `measure.reading` and `surface.maxWidth` resolve to the same effective value
---
## Summary
- Core sizing defines primitives plus the responsive ramps
- Semantic sizing defines a small set of stable geometry contracts
- `hit` is ergonomic, not visual
- `icon.*` and `identity.*` are visual, not interactive
- `measure.reading` and `surface.maxWidth` solve different problems
- Responsiveness lives in the core engine, not in components
- The system stays small, predictable, and scalable
---
## Spacing
Spacing tokens define the **repeatable distances** used to build rhythm, hierarchy, alignment, and ergonomics across interfaces.
This system is built on **two explicit layers**:
1. **Core Tokens** — intent-free primitives and the **single responsiveness engine**
2. **Semantic Tokens** — stable layout patterns consumed by UI code
Components must always consume **semantic spacing**, never core spacing directly.
> **Rule:** Core spacing is never referenced in components.
---
## Core Tokens
Core spacing tokens are intent-free primitives and the single source of truth for responsiveness.
They exist to:
- centralize fluid logic (the responsive engine lives here)
- keep semantic tokens as **aliases** (stable names, theme-tunable engine)
- make the system predictable (no ad-hoc coefficients in semantics)
### Core set
- **Primitive**: `core.spacing.engine.unit`
- **Steps** (fluid, engine-driven): `core.spacing.0`, `core.spacing.1`, `core.spacing.2`, `core.spacing.3`, `core.spacing.4`, `core.spacing.6`, `core.spacing.8`, `core.spacing.12`, `core.spacing.16`
- **Fixed steps** (non-fluid): `core.spacing.fixed.1`, `core.spacing.fixed.2`, `core.spacing.fixed.4`
> Keep the step set small. If you want `core.spacing.5`, you likely need a semantic mapping, not a new core step.
**Why a fixed scale exists beside the fluid one.** Most spacing is _rhythm_ and
belongs to the engine. A few semantic tokens instead guarantee a **resolved
outcome** — `inset.control.*` is one, because a control's box is its inset plus
its type over the `hit` floor (ADR-022), so a fluid inset would make the box
container-fluid. Those tokens need a value that does not move, and that value is
core's to hold: a semantic token is a reference, and a constant written into the
semantic layer breaks that rule while claiming an impossibility that does not
exist (model.md §8, ADR-023). The base theme sets the fixed steps to the
engine's own desktop bound, so a control resolves identically on wide surfaces
to the fluid step it references instead; that agreement is a theme choice, not a
contract. This mirrors `sizing`, which has carried both shapes from the start —
the fluid `ramp.*` beside the rem-anchored `hit`.
### Example
```js
const core = {
spacing: {
/**
* The Responsive Engine
* Container-first: scales with the inline size of the nearest query container.
* If no eligible container exists, cqi falls back to the small viewport unit for that axis (sv*).
*/
engine: {
unit: 'clamp(4px, 0.5cqi + 2px, 8px)',
},
/**
* Core steps reference the emitted CSS variable directly (not a {token.ref}).
* This preserves the CSS cascade so themes can override --tt-core-spacing-engine-unit at
* runtime (e.g. density mode) without recompiling every step.
*/
0: '0px',
/**
* Non-fluid steps — for semantic tokens whose resolved outcome is the
* guarantee rather than the rhythm (ADR-023). Plain values, because core
* is the layer that holds values.
*/
fixed: { 1: '6px', 2: '12px', 4: '24px' },
1: 'calc(1 * var(--tt-core-spacing-engine-unit))',
2: 'calc(2 * var(--tt-core-spacing-engine-unit))',
3: 'calc(3 * var(--tt-core-spacing-engine-unit))',
4: 'calc(4 * var(--tt-core-spacing-engine-unit))',
6: 'calc(6 * var(--tt-core-spacing-engine-unit))',
8: 'calc(8 * var(--tt-core-spacing-engine-unit))',
12: 'calc(12 * var(--tt-core-spacing-engine-unit))',
16: 'calc(16 * var(--tt-core-spacing-engine-unit))',
/** Tier-2 (optional, not default): container-aware unit (kept for explicitness) */
// engine.unitCq: 'clamp(4px, 0.6cqi, 8px)',
},
};
```
**Expected consumption pattern:** semantic tokens reference core tokens by alias.
---
## Semantic Tokens
Semantic spacing is anchored in **layout physics**, not UX categories.
### Token structure
```
{pattern}.{context}.{step?}
```
- `pattern`: `inset`, `gap`, `gutter`, `separation`
- `context`: `control`, `action`, `surface`, `stack`, `inline`, `page`, `section`, `interactive`
- `step`: `xs`, `sm`, `md`, `lg`, `xl`, `min`, `block`
`step` is only used in some cases.
#### Patterns:
| `{pattern}` | Description |
| :----------- | :----------------------------------------------------- |
| `inset` | padding inside elements |
| `gap` | spacing between siblings |
| `gutter` | structural layout padding (page/section) |
| `separation` | minimum ergonomic distance between interactive targets |
### Canonical shapes
- `inset.control.{sm|md|lg}`
- `inset.action.block`
- `inset.surface.{xs|sm|md|lg}`
- `gap.stack.{xs|sm|md|lg|xl}`
- `gap.inline.{xs|sm|md|lg|xl}`
- `gutter.{page|section}`
- `separation.interactive.min`
### Semantic Tokens Summary Table
> Default mappings below reflect the base theme (`baseTheme.ts`). They are a
> theme choice, not a contract — a theme may remap any step. What the contract
> guarantees is the ordering (see [validation rules](#errors-validation-must-fail-when)),
> not the specific core step.
| token | use when you are building… | contract (must be true) | default mapping (base theme) |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------- |
| `inset.control.sm` | compact controls | fixed — a non-fluid core step (ADR-022/023) | `core.spacing.fixed.1` |
| `inset.control.md` | default controls | fixed — a non-fluid core step (ADR-022/023) | `core.spacing.fixed.2` |
| `inset.control.lg` | large/prominent controls | fixed — a non-fluid core step (ADR-022/023) | `core.spacing.fixed.4` |
| `inset.action.block` | block padding of a command trigger — a CTA resolves taller (~40px desktop) than generic controls (~32px); inline padding stays `inset.control.lg` | bounded 8–9px range — a `clamp()` RawValue (model.md §8, ADR-021 addendum) | `clamp(8px, core.spacing.2, 9px)` |
| `inset.surface.xs` | anchored / row-framing surfaces — a gutter beside children that carry their own `inset.control` (popover, menu, tooltip, list container) | **fixed** — the outcome is the relationship to fixed-height children (ADR-022's argument one scale out) | `core.spacing.fixed.1` |
| `inset.surface.sm` | tight surfaces | `inset.surface ≥ inset.control` per step | `core.spacing.4` |
| `inset.surface.md` | default surfaces | `inset.surface ≥ inset.control` per step | `core.spacing.6` |
| `inset.surface.lg` | spacious surfaces | `inset.surface ≥ inset.control` per step | `core.spacing.8` |
| `gap.stack.xs` | tight vertical rhythm | sibling spacing via `gap` | `core.spacing.2` |
| `gap.stack.sm` | medium vertical rhythm | sibling spacing via `gap` | `core.spacing.4` |
| `gap.stack.md` | default vertical rhythm | sibling spacing via `gap` | `core.spacing.6` |
| `gap.stack.lg` | roomy vertical rhythm | sibling spacing via `gap` | `core.spacing.8` |
| `gap.stack.xl` | section-level rhythm | sibling spacing via `gap` | `core.spacing.12` |
| `gap.inline.xs` | **visual-only** tight grouping (icon + label) | never between interactive targets | `core.spacing.1` |
| `gap.inline.sm` | inline grouping | ascending inline scale | `core.spacing.2` |
| `gap.inline.md` | looser inline grouping | ascending inline scale | `core.spacing.3` |
| `gap.inline.lg` | spacious inline grouping | ascending inline scale | `core.spacing.4` |
| `gap.inline.xl` | wide inline grouping | ascending inline scale | `core.spacing.6` |
| `gutter.page` | page outer padding | bounded, structural | `clamp(core.spacing.6, core.spacing.12, core.spacing.16)` |
| `gutter.section` | section outer padding | bounded, structural; tighter than `page` | `clamp(core.spacing.4, core.spacing.8, core.spacing.16)` |
| `separation.interactive.min` | dense interactive target clusters | only between click/tap/focusable targets | `clamp(8px, core.spacing.3, 16px)` |
---
#### Example
```js
const spacing = {
inset: {
control: {
// The NON-FLUID step scale, not the engine steps (ADR-022): a control's
// box is its inset + type over the `hit` floor, so the inset is
// outcome-bearing — a fluid inset makes the box container-fluid, against
// ADR-019/020. Core holds the fixed values (`core.spacing.fixed.*`, set
// to the engine's own desktop bound so wide surfaces are unchanged) and
// this layer references them like every other semantic spacing token —
// a literal here was the wrong mechanism for a right ruling (ADR-023).
sm: 'core.spacing.fixed.1',
md: 'core.spacing.fixed.2',
lg: 'core.spacing.fixed.4',
},
action: {
// Bounded range, not a step (model.md §8): the engine's unit steps
// straddle the 8–9px command block inset. Inline stays inset.control.lg.
block: 'clamp(8px, {core.spacing.2}, 9px)',
},
surface: {
sm: 'core.spacing.4',
md: 'core.spacing.6',
lg: 'core.spacing.8',
},
},
gap: {
stack: {
xs: 'core.spacing.2',
sm: 'core.spacing.4',
md: 'core.spacing.6',
lg: 'core.spacing.8',
xl: 'core.spacing.12',
},
inline: {
xs: 'core.spacing.1', // visual-only tight grouping — never between focusable targets
sm: 'core.spacing.2',
md: 'core.spacing.3',
lg: 'core.spacing.4',
xl: 'core.spacing.6',
},
},
gutter: {
page: 'clamp({core.spacing.6}, {core.spacing.12}, {core.spacing.16})',
section: 'clamp({core.spacing.4}, {core.spacing.8}, {core.spacing.16})',
},
separation: {
interactive: {
min: 'clamp(8px, {core.spacing.3}, 16px)',
},
},
};
```
---
## Rules of Engagement (non-negotiable)
1. **Semantic-only consumption:** components use semantic spacing only.
2. **Gap-first:** sibling spacing uses `gap` (Flex/Grid) by default.
3. **Inset is for padding:** `inset.*` is only for internal padding.
4. **Gutters are structural:** use `gutter.*` for page/section layout padding.
5. **Separation is ergonomic:** `separation.interactive.min` is only for interactive targets.
6. **No responsive logic in components:** responsiveness lives in Core (`core.spacing.engine.unit`), not in UI code.
## Decision Matrix (pick fast)
1. **Padding inside an element?** → `inset.control.*` / `inset.surface.*`
2. **Spacing between siblings?** → `gap.stack.*` / `gap.inline.*`
3. **Page/section structure?** → `gutter.page` / `gutter.section`
4. **Dense cluster of interactive targets?** → `separation.interactive.min`
---
## Usage Examples
| Usage | Token |
| :---------------------------------- | :---------------------------------- |
| Stack (vertical rhythm) | `{gap: gap.stack.md}` |
| Inline group (visual grouping) | `{gap: gap.inline.sm}` |
| Surface padding | `{padding: inset.surface.md}` |
| Page gutter | `{padding-inline: gutter.page}` |
| Dense toolbar (interactive targets) | `{gap: separation.interactive.min}` |
> Build output may expose semantic tokens as CSS variables (as shown above) or as framework-specific bindings. The semantic names remain the API.
---
## Output Guidance (Web)
The following sections are specific to CSS/web output and do not affect the semantic contract.
### Flex `gap` fallback (only if required)
If your support matrix includes environments without flex-gap support, emit a fallback:
```js
const rowStyles = {
display: 'flex',
flexDirection: 'row',
/* Preferred */
gap: 'gap.inline.sm',
/* Fallback */
'@supports not (gap: 1rem)': {
'& > * + *': {
marginLeft: 'gap.inline.sm',
},
},
};
```
---
## Theming & Density (allowed knobs)
Themes may tune spacing without renaming semantic tokens.
1. **Tune `core.spacing.engine.unit`** (global density + responsiveness)
- denser: lower clamp bounds
- airier: higher clamp bounds
2. **Optional density mode (rare)**
If multiple UI densities are truly needed, remap only:
- `inset.control.*`
- `gap.*` (stack + inline aliases)
Keep `gutter.*` and `separation.*` conservative.
---
### Container-Aware Spacing (optional)
For highly modular layouts (cards in grids, split panes), you may introduce:
- `core.spacing.engine.unitCq = clamp(4px, 0.6cqi, 8px)`
This is **not default**. Use it only in layout primitives/surfaces explicitly designed for container scaling.
---
## Validation
### Errors (validation must fail when)
- inset order breaks:
- `inset.control.sm > inset.control.md`
- `inset.control.md > inset.control.lg`
- `inset.surface.sm > inset.surface.md`
- `inset.surface.md > inset.surface.lg`
- a surface inset step is tighter than the corresponding control inset step
(compared in resolved px at the engine's floor, since the two sides have
different shapes):
- `inset.surface.sm < inset.control.sm`
- `inset.surface.md < inset.control.md`
- `inset.surface.lg < inset.control.lg`
- a control inset rides the fluid engine (or any formula) instead of resolving
to a fixed px — the control inset is outcome-bearing (ADR-022): a control's
box is its inset + type over the `hit` floor, so a fluid inset makes the box
container-fluid, against ADR-019/020
- a control inset holds the fixed value as a literal in the semantic layer
instead of referencing a non-fluid core step (`core.spacing.fixed.*`) — the
ruling is about the resolved outcome, not about who holds the number, and a
bare constant in the semantic layer breaks "semantic references core only"
(model.md §2/§8, ADR-023)
- any `gap.stack.*` token resolves to anything other than a `core.spacing.*` step alias
- stack gap order breaks:
- `gap.stack.xs > gap.stack.sm`
- `gap.stack.sm > gap.stack.md`
- `gap.stack.md > gap.stack.lg`
- `gap.stack.lg > gap.stack.xl`
- `gap.inline.xs > gap.inline.sm`
- `gutter.page` is not a bounded `clamp(...)` contract
- `gutter.section` is not a bounded `clamp(...)` contract
- `gutter.*` introduces direct responsive logic such as `cqi`, `cqmin`, `cqmax`, `vi`, `vw`, `%`, media queries, or breakpoint logic instead of composing from `core.spacing.*`
- `gutter.page` resolves smaller than `gutter.section` at any bound
- `separation.interactive.min` is not a bounded `clamp(...)` contract
- `separation.interactive.min` introduces direct responsive logic such as `cqi`, `cqmin`, `cqmax`, `vi`, `vw`, `%`, media queries, or breakpoint logic instead of composing from `core.spacing.*`
- `separation.interactive.min` has a minimum bound below `5px`
- any semantic spacing token other than `gutter.*` or `separation.interactive.min` defines its own raw formula instead of aliasing core spacing steps
- generated output does not emit a viewport-safe fallback before container-based overrides
- generated output does not gate container-based overrides behind `@supports (width: 1cqi)`
### Warning (validation should warn when)
- adjacent `inset.control.*` steps resolve to the same effective value
- adjacent `inset.surface.*` steps resolve to the same effective value
- adjacent `gap.stack.*` steps resolve to the same effective value
- `gap.inline.xs` resolves to the same effective value as `gap.inline.sm`
- `gutter.page` and `gutter.section` resolve to the same effective contract
- `separation.interactive.min` resolves to the same effective value as `gap.inline.sm`
---
## Summary
- One responsiveness engine: `core.spacing.engine.unit`
- Small core step set: `core.spacing.{0..16}` (sparse)
- Small semantic set: inset / gap / gutter / separation
- Gap-first, semantic-only consumption
- Responsive by contract, no breakpoint logic in components
---
## Typography
Typography tokens define the **text system** of ttoss: font families, weights, size ramps, line-height, letter-spacing, and **semantic text styles**.
Typography must be:
- **Readable** — supports long-form content, microcopy, and scanning.
- **Hierarchical** — communicates importance and structure without visual noise.
- **Robust** — survives 200% zoom, user text-spacing overrides, and locale/script differences.
- **Natively responsive** — responsiveness lives in the token engine, not in component code.
- **Small and predictable** — avoids token-per-component drift.
> Key principle: **typography is not a component**. It is a **global contract** that components consume.
This system is built on **two explicit layers**:
1. **Core Tokens** — intent-free primitives
2. **Semantic Tokens** — stable text style contracts consumed by UI code
> **Rule:** Core typography is never referenced in components. Components must always consume semantic typography.
### Scope: Tokens vs Text Components vs HTML
Typography tokens define **styles**. They do not define document structure.
- **HTML semantics** (`h1…h6`, `p`, `label`, etc.) express meaning and accessibility.
- **Text components** (e.g., `Text`, `Heading`) are implementation APIs that choose:
- the **HTML element** (`as="h2"`) for semantics
- the **semantic token** (`style="text.title.md"`) for appearance
- **Design tokens** define the style contracts (`text.title.md`) and the primitives they reference.
> Tag choice (`h2`) and style choice (`text.title.md`) are intentionally decoupled.
---
## Core Tokens
Core tokens are intent-free primitives and the single source of truth for responsiveness.
They exist to:
- centralize fluid logic (all `clamp()` formulas live here)
- keep semantic tokens as **aliases** (stable names, theme-tunable engine)
- make the system predictable (no ad-hoc coefficients in semantics)
### Output Guidance (Web)
The following is specific to CSS/web output and does not affect the semantic contract.
1. A query container rule for layout surfaces (recommended):
```css
.tt-container {
container-type: inline-size;
}
```
2. A robust fallback strategy in build output:
- emit a viewport-safe fallback first
- override with container units when supported
```css
:root {
--tt-core-font-scale-text-3: clamp(16px, calc(0.8vi + 12px), 18px);
--tt-core-font-scale-display-3: clamp(28px, calc(1.6vi + 20px), 40px);
}
@supports (width: 1cqi) {
:root {
--tt-core-font-scale-text-3: clamp(16px, calc(0.8cqi + 12px), 18px);
--tt-core-font-scale-display-3: clamp(28px, calc(1.6cqi + 20px), 40px);
}
}
```
3. The core token set below (ramps + primitives).
### Core Token Set
Core typography is composed of **two groups**:
1. **Font primitives** — fundamental typographic properties.
2. **Size ramps** — the responsive engine that controls typographic scale.
#### Font Primitives
| Category | Tokens | Notes |
| :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Font families** | `core.font.family.sans`, `core.font.family.serif` _(optional)_, `core.font.family.mono` | Defines the font stacks used across the system. |
| **Font weights** | `core.font.weight.regular` (400), `core.font.weight.medium` (500), `core.font.weight.semibold` (600), `core.font.weight.bold` (700) | If using variable fonts, weights may be tuned at the theme level. Components still consume semantic styles only. |
| **Leading (line-height)** | `core.font.leading.tight`, `core.font.leading.snug`, `core.font.leading.normal`, `core.font.leading.relaxed` | Unitless multipliers for scalable line-height. |
| **Tracking (letter-spacing)** | `core.font.tracking.tight`, `core.font.tracking.normal`, `core.font.tracking.wide` | `tight` may be used for large headings. `wide` is intended for short labels; avoid for body text. |
| **Optical sizing** _(optional)_ | `core.font.optical.auto`, `core.font.optical.none` | Exhaustive `font-optical-sizing` keyword set (closed by CSS spec). |
| **Numeric features** _(optional)_ | `core.font.numeric.proportional`, `core.font.numeric.tabular`, `core.font.numeric.lining`, `core.font.numeric.oldstyle`, `core.font.numeric.slashedZero`, `core.font.numeric.ordinal`, `core.font.numeric.normal` | Standalone `font-variant-numeric` keywords. `tabular` for dashboards; `slashedZero` for financial/code contexts; combine values at the consumer site (e.g. `tabular-nums slashed-zero`). |
#### Size Ramps (Responsive Engine)
Ramps define the **responsive typographic scale**.
Each ramp is expressed using `clamp(min, preferred, max)`.
| Ramp | Tokens | Purpose |
| :---------------- | :----------------------------- | :------------------------------------------------- |
| **Text scale** | `core.font.scale.text.1..6` | Body text, labels, and dense UI typography. |
| **Display scale** | `core.font.scale.display.1..6` | Headings, titles, and high-hierarchy display text. |
> **Rule:** Semantic typography styles must map to ramp steps.
> Semantic tokens never define new `clamp()` formulas.
### Example (Core Typography Definition)
```js
const coreTypography = {
font: {
family: {
sans: 'ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial, "Apple Color Emoji", "Segoe UI Emoji"',
mono: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace',
},
weight: {
regular: 400,
medium: 500,
semibold: 600,
bold: 700,
},
leading: {
tight: 1.15,
snug: 1.25,
normal: 1.5,
relaxed: 1.7,
},
tracking: {
tight: '-0.02em',
normal: '0em',
wide: '0.04em',
},
optical: {
auto: 'auto',
none: 'none',
},
numeric: {
proportional: 'proportional-nums',
tabular: 'tabular-nums',
lining: 'lining-nums',
oldstyle: 'oldstyle-nums',
slashedZero: 'slashed-zero',
ordinal: 'ordinal',
normal: 'normal',
},
/**
* Responsive size scale (container-first). Theme must emit a viewport-safe fallback first,
* then override these when supported via @supports (width: 1cqi).
*/
scale: {
text: {
1: 'clamp(12px, calc(0.6cqi + 10px), 14px)',
2: 'clamp(14px, calc(0.7cqi + 11px), 16px)',
3: 'clamp(16px, calc(0.8cqi + 12px), 18px)',
4: 'clamp(18px, calc(0.9cqi + 13px), 20px)',
5: 'clamp(20px, calc(1.0cqi + 14px), 24px)',
6: 'clamp(24px, calc(1.2cqi + 16px), 28px)',
},
display: {
1: 'clamp(20px, calc(1.2cqi + 16px), 28px)',
2: 'clamp(24px, calc(1.4cqi + 18px), 32px)',
3: 'clamp(28px, calc(1.6cqi + 20px), 40px)',
4: 'clamp(32px, calc(1.8cqi + 22px), 48px)',
5: 'clamp(40px, calc(2.2cqi + 26px), 64px)',
6: 'clamp(48px, calc(2.6cqi + 30px), 80px)',
},
},
},
};
```
**Expected consumption pattern:** semantic styles reference core tokens by alias
(e.g., `text.body.md → core.font.scale.text.3`, `text.display.lg → core.font.scale.display.5`).
---
## Semantic Tokens
Semantic typography tokens are the only typography API for components.
### Token structure
```
text.{family}.{step}
```
- `family`: `display | headline | title | body | label | action | code`
- `step`: `lg | md | sm` (code uses `md | sm`)
#### Text Families
Each text family represents a distinct typographic role in the interface.
| `family` | Meaning |
| :--------- | :------------------------------------------------------------------------------------------------------------------------------ |
| `display` | Large, high-impact text used for hero sections or prominent page headers. Intended for strong visual hierarchy and limited use. |
| `headline` | Section or page headings that structure content and guide scanning through the interface. |
| `title` | Titles for surfaces such as cards, panels, dialogs, and structured UI sections. |
| `body` | Default text for paragraphs, descriptions, and long-form reading. Optimized for readability. |
| `label` | Short UI text such as field labels, badges, and metadata. |
| `action` | Command-trigger text (Button/ToggleButton) — semibold, single `md` step; CTAs carry more weight than the chrome around them. |
| `code` | Monospaced text for code snippets, logs, identifiers, or technical data. |
### Canonical semantic set
- `text.display.{lg|md|sm}`
- `text.headline.{lg|md|sm}`
- `text.title.{lg|md|sm}`
- `text.body.{lg|md|sm}`
- `text.label.{lg|md|sm}`
- `text.action.md`
- `text.code.{md|sm}`
> Keep this set stable. Add new families only if they represent a genuinely new typographic function.
### Numeric variants are a component-layer modifier, not a semantic style
`font-variant-numeric` (e.g. `tabular-nums` for dashboards and tables, `slashed-zero` for financial/code contexts) is **not** exposed as a semantic text token, by design. It is orthogonal to the type role — any family (`body`, `label`, a stat number) may need tabular figures — so baking it into the role styles would multiply the set combinatorially. And its values are **fixed CSS keywords**, not theme-variable, so a semantic token would add indirection without adding a themeable decision.
Apply it at the component/pattern layer, directly, on top of a semantic text style:
```css
.stat-value {
font: var(--tt-text-label-md); /* semantic role */
font-variant-numeric: tabular-nums; /* component-layer modifier */
}
```
This mirrors how edge-selection works for [borders](./borders.md#scope-tokens-vs-components-vs-edge-selection): the token carries the role; the component chooses the per-usage rendering refinement. `core.font.numeric.*` exists to register the keyword set (and to compose into a `TextStyle` if a future role genuinely requires a fixed numeric variant) — it is not a gap in the semantic surface.
### Semantic Tokens Summary Table
| token | use when you are building… | contract (must be true) | default mapping |
| :----------------- | :---------------------------- | :--------------------------------- | :---------------------------------------------------------------------------------- |
| `text.display.lg` | hero display / landing hero | strongest hierarchy; avoid overuse | `core.font.scale.display.5`, `core.font.weight.bold`, `core.font.leading.tight` |
| `text.display.md` | large display headings | high hierarchy | `core.font.scale.display.4`, `core.font.weight.bold`, `core.font.leading.tight` |
| `text.display.sm` | smaller display headings | high hierarchy | `core.font.scale.display.3`, `core.font.weight.semibold`, `core.font.leading.tight` |
| `text.headline.lg` | page/section headline | clear hierarchy | `core.font.scale.display.3`, `core.font.weight.semibold`, `core.font.leading.snug` |
| `text.headline.md` | section headline | clear hierarchy | `core.font.scale.display.2`, `core.font.weight.semibold`, `core.font.leading.snug` |
| `text.headline.sm` | small headline | compact hierarchy | `core.font.scale.display.1`, `core.font.weight.semibold`, `core.font.leading.snug` |
| `text.title.lg` | surface titles (cards/modals) | title-like, not shouting | `core.font.scale.text.6`, `core.font.weight.semibold`, `core.font.leading.snug` |
| `text.title.md` | default surface title | title-like | `core.font.scale.text.5`, `core.font.weight.semibold`, `core.font.leading.snug` |
| `text.title.sm` | compact titles | title-like | `core.font.scale.text.4`, `core.font.weight.medium`, `core.font.leading.snug` |
| `text.body.lg` | long-form body (comfortable) | readable; avoid tight leading | `core.font.scale.text.4`, `core.font.weight.regular`, `core.font.leading.normal` |
| `text.body.md` | default body | readable default | `core.font.scale.text.3`, `core.font.weight.regular`, `core.font.leading.normal` |
| `text.body.sm` | dense body / secondary text | still readable | `core.font.scale.text.2`, `core.font.weight.regular`, `core.font.leading.normal` |
| `text.label.lg` | strong labels | short text; supports tracking | `core.font.scale.text.3`, `core.font.weight.medium`, `core.font.leading.snug` |
| `text.label.md` | default labels | short text | `core.font.scale.text.2`, `core.font.weight.medium`, `core.font.leading.snug` |
| `text.label.sm` | small labels / captions | short text | `core.font.scale.text.1`, `core.font.weight.medium`, `core.font.leading.snug` |
| `text.code.md` | code/monospace blocks | mono; stable glyph width helpful | `core.font.scale.text.2`, `core.font.family.mono`, `core.font.leading.normal` |
| `text.code.sm` | inline code / dense logs | mono; compact | `core.font.scale.text.1`, `core.font.family.mono`, `core.font.leading.normal` |
---
#### Example
```js
const semanticTypography = {
text: {
display: {
lg: {
fontFamily: '{core.font.family.sans}',
fontSize: '{core.font.scale.display.5}',
fontWeight: '{core.font.weight.bold}',
lineHeight: '{core.font.leading.tight}',
letterSpacing: '{core.font.tracking.tight}',
fontOpticalSizing: '{core.font.optical.auto}',
},
md: {
fontFamily: '{core.font.family.sans}',
fontSize: '{core.font.scale.display.4}',
fontWeight: '{core.font.weight.bold}',
lineHeight: '{core.font.leading.tight}',
letterSpacing: '{core.font.tracking.tight}',
fontOpticalSizing: '{core.font.optical.auto}',
},
sm: {
fontFamily: '{core.font.family.sans}',
fontSize: '{core.font.scale.display.3}',
fontWeight: '{core.font.weight.semibold}',
lineHeight: '{core.font.leading.tight}',
letterSpacing: '{core.font.tracking.tight}',
fontOpticalSizing: '{core.font.optical.auto}',
},
},
headline: {
lg: {
fontFamily: '{core.font.family.sans}',
fontSize: '{core.font.scale.display.3}',
fontWeight: '{core.font.weight.semibold}',
lineHeight: '{core.font.leading.snug}',
letterSpacing: '{core.font.tracking.normal}',
fontOpticalSizing: '{core.font.optical.auto}',
},
md: {
fontFamily: '{core.font.family.sans}',
fontSize: '{core.font.scale.display.2}',
fontWeight: '{core.font.weight.semibold}',
lineHeight: '{core.font.leading.snug}',
letterSpacing: '{core.font.tracking.normal}',
fontOpticalSizing: '{core.font.optical.auto}',
},
sm: {
fontFamily: '{core.font.family.sans}',
fontSize: '{core.font.scale.display.1}',
fontWeight: '{core.font.weight.semibold}',
lineHeight: '{core.font.leading.snug}',
letterSpacing: '{core.font.tracking.normal}',
fontOpticalSizing: '{core.font.optical.auto}',
},
},
title: {
lg: {
fontFamily: '{core.font.family.sans}',
fontSize: '{core.font.scale.text.6}',
fontWeight: '{core.font.weight.semibold}',
lineHeight: '{core.font.leading.snug}',
letterSpacing: '{core.font.tracking.normal}',
fontOpticalSizing: '{core.font.optical.auto}',
},
md: {
fontFamily: '{core.font.family.sans}',
fontSize: '{core.font.scale.text.5}',
fontWeight: '{core.font.weight.semibold}',
lineHeight: '{core.font.leading.snug}',
letterSpacing: '{core.font.tracking.normal}',
fontOpticalSizing: '{core.font.optical.auto}',
},
sm: {
fontFamily: '{core.font.family.sans}',
fontSize: '{core.font.scale.text.4}',
fontWeight: '{core.font.weight.medium}',
lineHeight: '{core.font.leading.snug}',
letterSpacing: '{core.font.tracking.normal}',
fontOpticalSizing: '{core.font.optical.auto}',
},
},
body: {
lg: {
fontFamily: '{core.font.family.sans}',
fontSize: '{core.font.scale.text.4}',
fontWeight: '{core.font.weight.regular}',
lineHeight: '{core.font.leading.normal}',
letterSpacing: '{core.font.tracking.normal}',
fontOpticalSizing: '{core.font.optical.auto}',
},
md: {
fontFamily: '{core.font.family.sans}',
fontSize: '{core.font.scale.text.3}',
fontWeight: '{core.font.weight.regular}',
lineHeight: '{core.font.leading.normal}',
letterSpacing: '{core.font.tracking.normal}',
fontOpticalSizing: '{core.font.optical.auto}',
},
sm: {
fontFamily: '{core.font.family.sans}',
fontSize: '{core.font.scale.text.2}',
fontWeight: '{core.font.weight.regular}',
lineHeight: '{core.font.leading.normal}',
letterSpacing: '{core.font.tracking.normal}',
fontOpticalSizing: '{core.font.optical.auto}',
},
},
label: {
lg: {
fontFamily: '{core.font.family.sans}',
fontSize: '{core.font.scale.text.3}',
fontWeight: '{core.font.weight.medium}',
lineHeight: '{core.font.leading.snug}',
letterSpacing: '{core.font.tracking.normal}',
fontOpticalSizing: '{core.font.optical.auto}',
},
md: {
fontFamily: '{core.font.family.sans}',
fontSize: '{core.font.scale.text.2}',
fontWeight: '{core.font.weight.medium}',
lineHeight: '{core.font.leading.snug}',
letterSpacing: '{core.font.tracking.normal}',
fontOpticalSizing: '{core.font.optical.auto}',
},
sm: {
fontFamily: '{core.font.family.sans}',
fontSize: '{core.font.scale.text.1}',
fontWeight: '{core.font.weight.medium}',
lineHeight: '{core.font.leading.snug}',
letterSpacing: '{core.font.tracking.wide}',
fontOpticalSizing: '{core.font.optical.auto}',
},
},
code: {
md: {
fontFamily: '{core.font.family.mono}',
fontSize: '{core.font.scale.text.2}',
fontWeight: '{core.font.weight.regular}',
lineHeight: '{core.font.leading.normal}',
letterSpacing: '{core.font.tracking.normal}',
fontVariantNumeric: '{core.font.numeric.tabular}',
},
sm: {
fontFamily: '{core.font.family.mono}',
fontSize: '{core.font.scale.text.1}',
fontWeight: '{core.font.weight.regular}',
lineHeight: '{core.font.leading.normal}',
letterSpacing: '{core.font.tracking.normal}',
fontVariantNumeric: '{core.font.numeric.tabular}',
},
},
},
};
```
---
## Rules of Engagement (non-negotiable)
1. **Semantic-only consumption:** components use only `text.*` styles.
2. **No responsive logic in components:** responsiveness lives in core ramps only.
3. **Tag ≠ style:** HTML element choice is semantic; style choice is visual contract (`text.*`).
4. **No `font-variation-settings` by default:** use standard properties (weight/width/optical sizing) unless you truly need a custom axis.
5. **Numeric stability in dashboards:** use tabular numbers where values update frequently (`text.code.*` or a dedicated numeric style if needed).
6. **Robustness under user settings:** UI must survive 200% text resize and user text spacing adjustments without losing content or functionality.
---
## Theming
Themes may tune:
- font size scale (`core.font.scale.*`) — the responsive engine
- font stacks (`core.font.family.*`)
- weights (`core.font.weight.*`)
- leading/tracking defaults (`core.font.leading.*`, `core.font.tracking.*`)
- optional features (`core.font.optical.*`, `core.font.numeric.*`)
Semantic token names **never change across themes**.
---
## Validation
### Errors (validation must fail when)
- leading order breaks:
- `tight >= snug`
- `snug >= normal`
- `normal >= relaxed`
- weight order breaks:
- `regular > medium`
- `medium > semibold`
- `semibold > bold`
- any emitted `fontOpticalSizing` value is not `auto` or `none`
- any emitted `fontVariantNumeric` value is not one of the standalone keywords (`proportional-nums`, `tabular-nums`, `lining-nums`, `oldstyle-nums`, `slashed-zero`, `ordinal`, `normal`) or a space-separated combination of them
- generated output does not emit a viewport-safe fallback before container-based overrides
- generated output does not gate container-based overrides behind `@supports (width: 1cqi)`
### Warning (validation should warn when)
- adjacent steps in the same semantic family resolve to the same effective text contract
---
## Summary
- Core defines primitives + responsive ramps (the engine)
- Semantic defines a small canonical set: display/headline/title/body/label (+ code)
- Components consume only semantic `text.*`
- Responsiveness is native (ramp-based), not component logic
- System is robust under accessibility stress (resize + text spacing)
---
## Z-Index
Z-index tokens define the **global layering system** of ttoss.
They do not describe visual style.
They define **which interface strata sit above others** in the normal stacking order of the application.
Z-index tokens are used for:
- sticky interface regions
- floating overlays
- blocking overlays
- transient topmost UI inside the normal application layer
They must be:
- **Structural** — represent interface strata, not components
- **Predictable** — form a small, stable hierarchy
- **Deliberate** — discourage arbitrary numbers
- **Context-aware** — work with stacking contexts, not against them
> Key principle: **z-index defines layer strata, not component names.**
This system is built on **two explicit layers**:
1. **Core Tokens** — intent-free numeric levels
2. **Semantic Tokens** — stable layer contracts consumed by UI code
Components must always consume **semantic z-index tokens**, never core z-index values directly.
> **Rule:** Core z-index tokens are never referenced in components.
---
## Scope: Z-Index vs Stacking Context vs Top Layer
Z-index only works **within the relevant stacking context**.
This means:
- a higher `z-index` does **not** guarantee that an element will appear above everything else
- ancestor stacking contexts can isolate descendants
- local layering and global layering are different concerns
Also, browser-managed **top layer** elements (such as modal dialogs or popovers promoted by the platform) are **outside** the normal z-index scale.
### This family governs
- the **normal application stacking system**
- viewport-level and app-level layer order
- semantic layer relationships inside the standard document tree
### This family does not govern
- the browser **top layer**
- local micro-layering inside a single component
- visual depth (that belongs to elevation)
> Z-index controls **ordering**, not depth.
> Elevation expresses depth.
> Top layer is a browser-level exception.
---
## Core Tokens
Core z-index tokens are intent-free numeric levels.
They define the ordered strata available to the system.
### Core set
| Token | Value | Meaning |
| :-------------------- | ----: | :---------------------------------------------- |
| `core.zIndex.level.0` | `0` | base application layer |
| `core.zIndex.level.1` | `100` | sticky layer |
| `core.zIndex.level.2` | `200` | overlay layer |
| `core.zIndex.level.3` | `300` | blocking layer |
| `core.zIndex.level.4` | `400` | transient top layer inside the normal app stack |
> Values are spaced intentionally to leave room for controlled local layering when necessary.
### Example
```js
const coreZIndex = {
zIndex: {
level: {
0: 0,
1: 100,
2: 200,
3: 300,
4: 400,
},
},
};
```
**Expected consumption pattern:** semantic z-index tokens reference core levels by alias.
---
## Semantic Tokens
Semantic z-index tokens define **global layer roles**.
They are intentionally anchored in **interface strata**, not component names.
### Token structure
```text
zIndex.layer.{stratum}
```
### Canonical semantic set
- `zIndex.layer.base`
- `zIndex.layer.sticky`
- `zIndex.layer.overlay`
- `zIndex.layer.blocking`
- `zIndex.layer.transient`
> Keep this set stable.
> Do not create component-specific z-index tokens by default (`zIndex.dropdown`, `zIndex.tooltip`, `zIndex.toast`, etc.).
### Semantic Tokens Summary Table
| token | use when you are building… | contract (must be true) | default mapping |
| :----------------------- | :---------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- | :-------------------- |
| `zIndex.layer.base` | page content and normal document flow | default application layer | `core.zIndex.level.0` |
| `zIndex.layer.sticky` | sticky headers, sticky navigation, anchored persistent bars | must remain above normal content while still inside the app stack | `core.zIndex.level.1` |
| `zIndex.layer.overlay` | non-blocking overlays such as dropdowns, menus, popovers, floating panels | floats above sticky/base content but does not block the whole app | `core.zIndex.level.2` |
| `zIndex.layer.blocking` | blocking overlays such as dialogs, sheets, blocking drawers | sits above other overlays and blocks interaction behind it | `core.zIndex.level.3` |
| `zIndex.layer.transient` | transient topmost UI inside the normal stack, such as toasts or tooltip-like transient overlays | highest application-controlled layer before browser top layer | `core.zIndex.level.4` |
### Example
```js
const semanticZIndex = {
zIndex: {
layer: {
base: '{core.zIndex.level.0}',
sticky: '{core.zIndex.level.1}',
overlay: '{core.zIndex.level.2}',
blocking: '{core.zIndex.level.3}',
transient: '{core.zIndex.level.4}',
},
},
};
```
---
## Stacking Context Awareness
Z-index tokens do **not** bypass stacking context rules.
Common properties that may create new stacking contexts include:
- `position: sticky`
- `opacity < 1`
- `transform`
- `filter`
- `isolation: isolate`
- `contain`
- `container-type`
- flex or grid items with explicit `z-index`
This means a correctly chosen semantic token can still appear “wrong” if the element lives inside an isolated stacking context.
> Use z-index tokens to define **intended stratum**.
> Use implementation discipline to avoid accidental stacking context traps.
---
## Local Layering vs Global Layering
This family defines **global application strata**.
Do not use global z-index tokens for every internal detail of a component.
Examples of **local layering**:
- a close button inside a dialog
- a sticky subheader inside a panel
- decorative layers inside a card
- internal handles, highlights, or overlays inside a component
These should usually be solved **locally**, within the component’s own stacking context.
> Global z-index tokens are for **cross-component layer relationships**.
> Local layering belongs to the component or pattern layer.
---
## Top Layer
Some browser features promote elements into the **top layer**, which sits above the normal stacking system.
Examples include:
- modal dialogs shown by the platform
- popovers promoted to top layer
- fullscreen elements
These are **not governed** by ttoss z-index tokens.
> Z-index tokens govern the normal application stack.
> The browser top layer is outside that contract.
---
## Rules of Engagement (non-negotiable)
1. **Semantic-only consumption**
Components use semantic z-index tokens only.
2. **Strata, not components**
Z-index tokens define interface layers, not component names.
3. **Do not use arbitrary large numbers**
Avoid `9999`, `99999`, or ad-hoc escalation.
4. **Do not treat z-index as a global guarantee**
Always consider stacking context boundaries.
5. **Use global tokens only for global layering**
Internal component layering should remain local whenever possible.
6. **Top layer is out of scope**
Do not try to model browser top-layer behavior as normal z-index tokens.
---
## Decision Matrix (pick fast)
1. **Is this normal page content?**
→ `zIndex.layer.base`
2. **Is this a persistent sticky interface region?**
→ `zIndex.layer.sticky`
3. **Is this a floating non-blocking overlay?**
→ `zIndex.layer.overlay`
4. **Is this a blocking overlay that owns interaction?**
→ `zIndex.layer.blocking`
5. **Is this a transient topmost UI element inside the normal application stack?**
→ `zIndex.layer.transient`
6. **Is this actually a browser top-layer element?**
→ z-index token does not govern it
---
## Usage Examples
| Usage | Token |
| :-------------------------------- | :----------------------- |
| Main page content | `zIndex.layer.base` |
| Sticky top navigation | `zIndex.layer.sticky` |
| Dropdown / menu / floating panel | `zIndex.layer.overlay` |
| Dialog / blocking drawer | `zIndex.layer.blocking` |
| Toast / transient tooltip-like UI | `zIndex.layer.transient` |
> Build output may expose semantic z-index tokens as CSS variables or framework-specific bindings. The semantic names remain the API.
---
## Theming
Z-index is usually **not themed**.
It is layout infrastructure, not brand expression.
If an application truly needs a different layer hierarchy, adjust the scale **as a system**, not by changing one token in isolation.
---
## Validation
### Errors (validation must fail when)
- core z-index order breaks:
- `level.0 >= level.1`
- `level.1 >= level.2`
- `level.2 >= level.3`
- `level.3 >= level.4`
- `core.zIndex.level.0` resolves below `0`
- semantic layer order breaks:
- `zIndex.layer.base >= zIndex.layer.sticky`
- `zIndex.layer.sticky >= zIndex.layer.overlay`
- `zIndex.layer.overlay >= zIndex.layer.blocking`
- `zIndex.layer.blocking >= zIndex.layer.transient`
### Warning (validation should warn when)
- adjacent core z-index levels differ by less than `10`
---
## Summary
- Z-index defines **global interface strata**
- Core tokens define numeric levels
- Semantic tokens define stable layer roles
- Components consume only semantic z-index tokens
- The family governs the **normal application stack**, not the browser top layer
- Local layering remains outside the global token contract
- The system stays small, predictable, and durable
---
## Governance
Design tokens are a public contract between design, themes, and components.
Governance protects three things:
- stable semantic names
- clear separation between core and semantic tokens
- safe evolution of the system over time
## Core rule
Components consume **semantic tokens only** for meaning-bearing families.
Infrastructure-only families (e.g., breakpoints) do not define a semantic layer — their tokens are consumed directly by layout systems and applications. See [Token Model — Invariant 7](./model.md) for the architectural rationale.
Core tokens of meaning-bearing families are foundation values for themes and token composition. They are not the public API for components.
## When to create a token
Create a token only when all of the following are true:
- the need cannot be expressed by an existing semantic token
- the need is reusable across multiple components or patterns
- the name fits the existing taxonomy
Prefer reuse before creation.
## What may change
### Add a core token
Add a core token when the system needs a new foundation value, such as a new color, size, radius, duration, or scale step.
Rules:
- core tokens define values, not intent
- adding a core token must not bypass the semantic layer
- new core tokens should extend the existing system, not create a parallel vocabulary
### Change a core token
A core value may change when a theme or foundation needs to evolve.
Rules:
- core value changes belong to theme or foundation evolution
- keep the token meaning the same
- evaluate impact on all semantic mappings and supported modes
- modes must remap semantic references, not mutate core values
### Add or change a semantic token
A semantic token may be added or remapped when the system needs a new stable design intention.
Rules:
- semantic tokens define intent, not raw value
- semantic names are part of the public API
- changing a semantic mapping is allowed only when meaning stays the same
- changing a semantic token’s meaning is not allowed
If the intention changes, create a new token and deprecate the old one.
## Contract checks
Every token change must pass validation before merge. What is checked, where each rule lives, and how severity works are defined in [Validation and Build](./validation.md). If a rule can be validated automatically, it should be validated automatically.
## Deprecation
Do not remove tokens without deprecation first.
When a token is no longer recommended:
1. mark it as deprecated in the token source
2. provide the replacement
3. allow time for migration
4. remove it in the next major version
Every deprecation records the deprecated token name, the replacement (or an explicit statement that none exists), the version that introduced the deprecation, and the target version for removal.
Deprecation is the preferred path for contract changes.
## Versioning
Tokens follow semantic versioning.
- **PATCH**: documentation fixes, metadata fixes, or internal corrections that do not change the public token contract
- **MINOR**: backward-compatible additions, new tokens, new aliases, or deprecations
- **MAJOR**: removals, renames, meaning changes, or any other breaking contract change
Remapping a semantic token to a different core token while meaning is preserved is MINOR or PATCH — the name and its meaning are the contract, not the resolved value. A meaning change is never a remap: it is a new token plus deprecation of the old one.
## Review
Each proposal should answer:
- what problem exists
- why reuse is not enough
- what token is being added, changed, or deprecated
- what impact exists on themes and components
Design reviews semantic fit.
Engineering reviews implementation and validation.
Merge only when the contract remains coherent.
## Principle
Prefer a smaller vocabulary with stronger meaning.
A token system stays scalable by making reuse easy, naming stable, and change deliberate.
---
## Design Tokens
Design tokens are the **vocabulary** of the design system. They separate **raw values** from **meaning**, so design decisions stay consistent across themes, components, patterns, and platforms.
> **In one sentence:** raw values live in `core`, design intent lives in `semantic`, and components only consume `semantic`.
---
## Hello, token
A primary button. Three pieces are needed: a background, a border, and a text color. All three come from the **semantic** layer:
```tsx
// ✅ what a component actually consumes
style={{
backgroundColor: theme.semantic.colors.action.primary.background.default,
borderColor: theme.semantic.colors.action.primary.border.default,
color: theme.semantic.colors.action.primary.text.default,
borderRadius: theme.semantic.radii.control,
padding: theme.semantic.spacing.inset.control.md,
minHeight: theme.semantic.sizing.hit,
}}
```
Each semantic token resolves to a **core** value. For example, `action.primary.background.default` resolves to `core.colors.neutral.1000`. Components never reference `core` directly — that is the contract.
Dark mode, high-contrast mode, or a new theme **do not change** this component. Only the `semantic → core` mapping changes.
> Want to pick tokens fast? Jump to [Quick Reference](./quick-reference.md).
---
## Model
The system follows a layered architecture:
```text
raw values → core tokens → semantic tokens → components → patterns → applications
```
- **Core tokens** hold raw, themeable values (`#94A3B8`, `16px`, `200ms`…)
- **Semantic tokens** hold stable design meaning (`action.primary.background`, `spacing.inset.control.md`…)
- **Components and patterns** consume semantic tokens only
For the architectural contract, see [Token Model](./model.md).
## Categories
The system is organized into two parts:
### Foundation
Foundation tokens define the core building blocks of UI systems:
- **Colors**
- **Typography**
- **Spacing**
- **Sizing**
- **Radii**
- **Borders**
- **Elevation**
- **Opacity**
- **Motion**
- **Z-Index**
- **Breakpoints**
Each family defines its own contract, and where applicable its own semantic grammar.
### Data Visualization
Data Visualization extends the system for **analytical meaning**.
It adds a controlled semantic layer for:
- analytical colors
- non-color encodings
- geospatial overlay semantics
This extension exists because analytical visualization introduces meaning that is not equivalent to standard UI semantics.
For the Data Visualization model, see [Data Visualization](./data-visualization/index.md) and [Model](./data-visualization/dataviz-model.md).
## Themes and Modes
Themes and modes allow the system to vary without changing semantic meaning.
- **Themes** may change core values and semantic mappings
- **Modes** remap semantic references to different core tokens — core values stay immutable
- **Semantic token names remain stable**
For details, see [Modes](./modes.md). To design or review a theme — including the Theme Brief and Formal Style Profile formats — see [Theme Authoring](./theme-authoring.md).
> **Implementation:** See [Theme Provider](/docs/design/theme-provider) for how themes and modes are configured in ttoss.
## Governance and Validation
The system is governed and validated to preserve semantic stability over time.
- **Governance** defines how tokens evolve
- **Validation** protects the contract before build and release
For details, see [Governance](./governance.md) and [Validation and Build](./validation.md).
---
## Next Steps
- Need a token **now**? → [Quick Reference](./quick-reference.md).
- Want the architecture? → [Token Model](./model.md).
Then explore the token families:
- [Colors](./families/colors.md)
- [Typography](./families/typography.md)
- [Spacing](./families/spacing.md)
- [Sizing](./families/sizing.md)
- [Radii](./families/radii.md)
- [Borders](./families/borders.md)
- [Elevation](./families/elevation.md)
- [Opacity](./families/opacity.md)
- [Motion](./families/motion.md)
- [Z-Index](./families/z-index.md)
- [Breakpoints](./families/breakpoints.md)
- [Data Visualization](./data-visualization/index.md)
---
## Token Model
The token model defines the **architectural contract** of the system.
It establishes where values live, where meaning lives, what components may consume, and how the system evolves without semantic drift.
This document defines **global invariants**.
Family docs define family-specific grammars and rules.
---
## Core Principle
Separate **value** from **meaning**.
- **Core tokens** define raw, themeable values
- **Semantic tokens** define stable design meaning
- **Components and patterns** consume semantic tokens only
> Semantic tokens are the public API of the system.
### The flow in one picture
```text
raw value core token semantic token component
───────── ────────── ────────────── ─────────
"#020617" ──► core.colors.neutral.1000 ──► semantic.colors.action `); adding a member to this class requires the §6 cross-cutting gate.
### 3. Core is never consumed directly by UI code
Core tokens exist for:
- theme definition
- token composition
- controlled system evolution
They are not the API for components or product UI.
> **Exception:** Infrastructure-only families (see invariant 7) export values directly without a semantic layer. Their tokens are consumed by layout systems and applications, not by the semantic mapping pipeline.
### 4. Meaning must remain stable
- Themes may change core values and semantic mappings.
- Modes do not change values. They remap semantic tokens to different core tokens within the same theme.
- If meaning changes, create a new semantic token and deprecate the old one.
### 5. Names must express meaning, not appearance
Semantic names describe intent, role, context, dimension, state, or analytical function.
Do not name semantics by:
- hue
- raw style
- component
- mode
- chart type
- library behavior
### 6. No parallel vocabulary
Do not introduce new tokens that duplicate existing meaning.
Prefer reuse before creation.
> **Cross-cutting tokens are a registered class, not exceptions.** Every grammar has a residual: meanings that cross its axes. A token is _not_ parallel vocabulary when it answers a question that the principal grammar cannot ask in a single token — typically a system-wide concern that no `{ux}` owns. Cross-cutting tokens live as **siblings** of `semantic.colors.*`, never inside it, and coexist with per-context counterparts (`{ux}.{role}.border.focused`, etc.): per-context tokens answer "how does _this_ `{ux}` vary?", cross-cutting tokens answer "what is the _system_ default?".
>
> **Cross-cutting registry** (complete as of this writing):
>
> | Token | Question the grammar cannot ask | ADR |
> | :------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :------ |
> | `semantic.focus.ring.color` | system focus indicator when no `{ux}` applies | ADR-025 |
> | `semantic.overlay.scrim` | dimming of obscured content behind a blocking layer | — |
> | `semantic.overlay.outline` | boundary of a surface that **occludes** content — occlusion is neither role nor state, and it crosses UX contexts | ADR-027 |
> | `semantic.consequence.destructive.ink` | foreground of a destructive part that paints no surface — the grammar cannot combine valence with emphasis | ADR-025 |
> | `semantic.valence.{positive,caution,negative}.ink` | foreground of a part that _reports_ a valence while painting no surface — generalizes the consequence-ink argument | ADR-029 |
> | `semantic.rail.track` | unfilled part of a `ProgressBar`/`Meter`/`Slider` track — crosses `Feedback` and `Input`, darkens in dark mode while borders lighten | ADR-028 |
>
> Adding a cross-cutting token requires the same gate as a `RawValue` exception (§8): technical necessity, JSDoc on the token, and registration in this table.
### 7. Families own their grammar, not their architecture
Each family may define its own semantic grammar.
Examples:
- colors may use `ux.role.dimension.state`
- typography may use `text.family.step`
- radii may use `radii.contract`
- dataviz may use analytical roles
This is valid.
What must remain constant is the architecture:
- core = value
- semantic = meaning
- semantic = public API
**Infrastructure-only families.** Some families do not express durable UI meaning and therefore do not define a semantic layer. They export values directly as adaptation infrastructure — for example, [breakpoints](./families/breakpoints.md) define viewport thresholds consumed by layout systems, not semantic intent consumed by components. This is architecturally valid when the family serves as operational infrastructure rather than design meaning.
### 8. RawValue exceptions are rare, intentional, and registered
Semantic tokens must reference core tokens. A `RawValue` is permitted only when a `TokenRef` is technically impossible (e.g., `clamp()` expressions mixing units from multiple token paths, or CSS units with no core token equivalent such as `ch`).
**A bare constant is never a lawful `RawValue`.** Every entry below is a
_composition_ — a `clamp()`, an `rgba()`, a unit with no core home — because a
composition is the only thing a single `{token.path}` genuinely cannot express.
A plain value is the opposite case: it becomes a `TokenRef` the moment core
holds it, and core is the layer whose job is holding values (§1). So
"core has no step for this value" is a **missing core token**, never a
necessity — the fix is to add the step to core and reference it, and
`core.spacing.fixed.*` (the non-fluid spacing scale, added for exactly this
reason) is the precedent. `semantic.spacing.inset.control.*` shipped as a
literal `6px` under a necessity argument of that circular shape and was
corrected in ADR-023; the guard that enforces this now has no exception list.
Approval criteria — a semantic `RawValue` must satisfy all three:
1. **Technical necessity**: the value cannot be expressed as a single `{token.path}` reference.
2. **Local justification**: a JSDoc comment on the token explains the necessity.
3. **Audit registration**: the token is listed in the inventory below.
**Approved RawValue inventory** (complete list as of this writing):
| Token path | Reason |
| :-------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `semantic.spacing.gutter.page` | `clamp()` expression embedding multiple token refs — no single `TokenRef` can express responsive fluid gutters |
| `semantic.spacing.gutter.section` | same as above |
| `semantic.spacing.separation.interactive.min` | `clamp()` with mixed units (`px` + token ref) — minimum touch-target separation cannot be expressed as a pure token reference |
| `semantic.spacing.inset.action.block` | `clamp()` with mixed units — the command trigger's block padding is a bounded 8–9px range the engine's unit steps straddle (ADR-021 addendum; this entry was added late — the token shipped unregistered, against this section's own rule) |
| `semantic.sizing.measure.reading` | `ch` units — character-based measure has no core token equivalent |
| `semantic.overlay.scrim` | `rgba()` composing `{semantic.opacity.scrim}` — no single `TokenRef` can express a partial-opacity overlay color |
Any new `RawValue` in the semantic layer requires an entry in this table before merging.
#### CSS-coupled core tokens
A separate, narrower exception applies to the **core** layer: a small set of core tokens carry CSS-only constructs (`clamp()`, container-query units, or in-string `var(--tt-…)` self-references) because their behaviour is only meaningful through the CSS cascade. `toCssVars` emits the necessary viewport fallbacks and media-query overrides for these tokens; consumers reading them via `useResolvedTokens` will see the unprocessed expression.
Two patterns appear in this category:
1. **Fluid primitives** — `clamp()` + `cqi` expressions that need `@supports (width: 1cqi)` gating with viewport fallbacks emitted by `toCssVars` (`extractContainerQueryVars` + `toViewportFallback`).
2. **Cascade-preserving aliases** — values that reference their own group via `var(--tt-…)` rather than `{token.path}`. This is intentional: it keeps the family a **single point of override**. Replacing `var()` with a token ref would inline the underlying expression into every step, duplicating CQ-units across the `@supports` block and breaking single-source semantics.
| Token path | Pattern | Reason |
| :------------------------------- | :------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `core.spacing.engine.unit` | Fluid primitive (`clamp()` + `cqi`) | Single fluid base unit driving the spacing scale; viewport fallback emitted by `toCssVars` |
| `core.spacing.{1..16}` | Cascade-preserving alias (`calc(N * var(--tt-core-spacing-engine-unit))`) | Each step multiplies the engine unit; using `var()` keeps `engine.unit` as the single override surface |
| `core.font.scale.*` | Fluid primitive | Fluid type scale; viewport fallback emitted by `toCssVars` |
| `core.sizing.ramp.{ui,layout}.*` | Fluid primitive | Fluid sizing ramps; viewport fallback emitted by `toCssVars` |
| `core.sizing.hit.coarse` | Media-query override target | Scalar leaf. Surfaced via `@media (any-pointer: coarse)` against `semantic.sizing.hit`; `useResolvedTokens` substitutes it when `isCoarsePointer` is `true` |
Approval criteria mirror §8: technical necessity, JSDoc on the token, registration in this table. Non-CSS consumers (`useResolvedTokens`) receive the unresolved expression for these paths — that is the trade-off in exchange for a CSS-native cascade. When a non-CSS consumer of one of these tokens emerges, evaluate a per-token fallback strategy at that point rather than preemptively.
### 9. ThemeTokens naming conventions are intentional
`ThemeTokens` uses `colors`, `radii`, and `breakpoints` (plural) alongside singular family names. These three are genuinely collection-typed families — each names a set of discrete, enumerable members rather than a unitary concept. The naming is an explicit convention, not an inconsistency. No migration to singular is planned.
The same applies to the one registered family-name asymmetry: typography is stored as `core.font` but exposed semantically as `semantic.text`. The names differ because the layers hold different things — font primitives (families, weights, scales) versus composed text meaning (`display`, `headline`, `body`, …) — and the asymmetry is the convention, not a defect.
### 10. Tokens define meaning, not implementation
Tokens do not define:
- component APIs
- layout composition
- chart types
- rendering logic
- application behavior
Those concerns belong to components, patterns, and implementation.
### 11. Source-of-truth hierarchy
When the three artefacts disagree, resolve in this order:
1. **FSL Lexicon / Structural Language** — authority over _vocabulary and identity_ (what each term means; which Entity Kinds are disjoint).
2. **`Types.ts`** — authority over _contract enforcement_ (which tokens exist and with what shape).
3. **Family docs** (this folder) — authority over _consumer guidance_ (how to pick a token in a real case).
Identity wins over enforcement wins over guidance when the conflict is about _meaning_. Enforcement wins over guidance whenever the conflict is about _what exists_. A divergence is a defect in the lower-priority artefact unless the higher-priority artefact is itself wrong by its own rules — in which case fix it there first.
---
## Themes and Modes
Themes and modes preserve **semantic meaning**, but they do not vary in the same way.
### Themes
A theme may change:
- core values
- semantic mappings
A theme must not create a parallel semantic vocabulary for the same system intent.
### Modes
Modes are controlled variations of a theme, such as light and dark.
Core tokens are immutable across modes. Modes operate at the **semantic mapping layer**:
- core token values do not change
- semantic token names do not change
- semantic token references may point to different core tokens
> When a semantic contract fails in a mode, remap — the doctrine lives in [Modes](./modes.md#relationship-to-the-token-model).
## Foundation and Extension
The system has a global foundation and a controlled extension model.
### Foundation
The foundation contains the general UI token families of the system, expressed as `core.{family} → semantic.{family}` pairs. There is no physical `foundation` key in `ThemeTokens` — `core.foundation` is conceptual shorthand for the full set of non-extension families.
### Extension
A new domain may extend the model when the foundation does not already solve the problem.
Example:
```text
core.dataviz → semantic.dataviz
```
An extension is valid only when all of the following are true:
1. the problem is not already solved by the foundation
2. the concept is stable and reusable
3. it can be expressed without component or implementation coupling
4. it does not duplicate existing meaning
If the need is local, solve it at the pattern or application layer instead.
## References and Composition
Semantic tokens typically reference core tokens.
This is what keeps names stable while allowing themes and modes to evolve.
Some families may also use composite tokens where the value is naturally applied as a bundle, such as typography styles or shadow recipes.
This is valid as long as the contract remains intact:
- core composites remain value-only
- semantic composites remain meaning-first
- UI code still consumes semantic tokens only
## Notation
`core.*` and `semantic.*` describe **architectural layers**, not required naming prefixes.
- semantic tokens are exposed directly as the public API
- core tokens may be namespaced or structured to prevent misuse
- storage and build organization may vary
> The architecture is fixed.
> The exact source notation is an implementation choice.
## Enforcement
The model must be enforceable.
Validation and build must preserve at least these guarantees:
- unique token names
- valid and resolvable references
- no circular references
- semantic tokens remain the public API
- core tokens are not consumed directly by UI code
- no parallel vocabularies are introduced
- semantic meaning does not change silently
- generated outputs preserve the contract
Family-specific validation may add stricter rules where needed.
## Change Rules
Changes must preserve the model. The change policy — when tokens may be added, remapped, deprecated, or removed, and how versioning applies — is defined in [Governance](./governance.md).
---
## Summary
The system stays scalable by protecting a small set of truths:
- core stores values
- semantic stores meaning
- semantic tokens are the public API for meaning-bearing families
- components and patterns consume semantic tokens only (infrastructure-only families are consumed directly)
- themes may change core values; modes remap semantic references within a theme
- families may differ in grammar; infrastructure-only families may skip the semantic layer entirely
- extensions are controlled
- validation and build preserve the contract
This is what makes the token system themeable, governable, and safe to evolve.
---
## Modes
A mode defines how a single theme adapts to a different environment while preserving the same semantic contract.
A mode is not a separate theme. It is a **controlled remapping of semantic references** within the same theme.
> Key principle: **core tokens are immutable. Modes remap which core tokens semantic tokens reference.**
---
## Relationship to the Token Model
The [Token Model](./model.md) defines two architectural layers:
- **core tokens** — an immutable palette of raw values
- **semantic tokens** — stable design meaning, expressed as references to core tokens
Modes operate at the **semantic mapping layer**.
When the mode changes:
- core token values do **not** change
- semantic token names do **not** change
- semantic token **references** may point to different core tokens
- components continue consuming the same semantic tokens
```text
light: action.primary.background.default → {core.colors.neutral.1000}
dark: action.primary.background.default → {core.colors.neutral.0}
```
Core tokens like `core.colors.neutral.1000` and `core.colors.neutral.0` retain their identity and value in both modes. What changes is which point in the palette the semantic token references.
> If a semantic contract fails in a mode, remap the semantic reference to a different core token — do not mutate the core value or rename the semantic token.
---
## What Changes Between Modes
Modes remap semantic references to preserve contrast, legibility, and depth in a different environment.
| Semantic family | Typical mode behavior | Guidance |
| :---------------------------------------- | :------------------------------ | :------------------------------------------------------------------------------------------------------------ |
| Color semantics (surfaces, text, borders) | **Most remappings happen here** | Remap to different positions in neutral, brand, and hue scales to preserve contrast |
| Elevation semantics | **May need remapping** | Shadow recipes that work on light surfaces often fail on dark ones — remap to appropriate core levels |
| Motion semantics | **Rarely remapped** | Some modes may justify reduced or adjusted motion — e.g., high-contrast modes that favor static presentations |
| Opacity semantics | **Rarely remapped** | Scrim/veil opacity may need adjustment when surface contrast changes between modes |
| Other semantic families | **Usually unchanged** | Remap only when the mode materially affects usability or perception |
Core tokens — palette scales, font primitives, spacing, sizing, radii, motion — remain unchanged. Modes should stay **minimal** and remap only what truly needs to change.
> If a mode requires values that do not exist in the current core palette (e.g., a shadow recipe that only works on dark surfaces), the correct path is to **enrich the theme's core tokens** with the missing recipes — not to mutate existing core values per mode. This preserves core immutability while giving semantic tokens enough palette depth to remap freely.
---
## Design Rules
### 1. Core tokens are the immutable palette
Core tokens define raw values: `core.colors.neutral.900` is always the darkest neutral, `core.colors.red.100` is always the lightest red. Modes never mutate these values.
This means `core.colors.neutral.0` is always the white end of the scale. If dark mode needs a dark background, the semantic surface token remaps to `core.colors.neutral.900` — it does not redefine the white end as a dark color.
### 2. Optimize semantic pairings, not isolated swatches
Modes succeed when semantic combinations still work together: text against background, borders against adjacent surfaces, focus indicators against surrounding context, raised surfaces against their environment.
Evaluate mode correctness by checking pairings, not individual swatches.
### 3. Remap neutrals first
Most mode adaptation comes from remapping semantic tokens to different positions in the neutral scale. Neutrals carry most surface and contrast work, so they are the primary lever.
### 4. Keep brand and hue remappings stable when possible
Semantic tokens that reference brand and hue scales should remap as little as practical between modes. But when a brand or hue reference breaks legibility or contrast in a mode, remap the semantic token to a different scale position.
### 5. No parallel vocabulary
Modes must never introduce mode-specific semantic names such as `textOnDark`, `darkBorder`, `lightSurface`, or `brandDark`.
Semantic token names remain identical across modes. Only the referenced core token changes.
### 6. Validate every mode independently
A semantic contract that works in one mode may fail in another. Each supported mode must be validated for text/background contrast, non-text contrast, focus visibility, selected/current state visibility, and surface separation.
---
## Accessibility Expectations
Modes must preserve accessibility, not just visual preference.
At minimum, validate these pairings in every supported mode:
- **normal text vs background** → `4.5:1`
- **large text vs background** → `3:1`
- **non-text UI indicators vs adjacent colors** → `3:1`
Focus indicators must remain clearly visible in each mode, not only technically present.
> Mode correctness is not "does dark mode look darker?" It is "does the semantic contract remain readable, perceivable, and usable?"
---
## Base Mode Direction
Each theme has a **base mode** — the primary environment it was designed for.
- A **light-first** theme defines its complete semantic mappings for light and provides alternate mappings only where needed for dark.
- A **dark-first** theme does the reverse.
A theme may also be intentionally **single-mode** when the product targets only one visual environment.
---
## Output Guidance
Modes should be implemented as **semantic remapping overrides**, not as duplicated token sets or mutated core values.
Typical output model:
1. emit the base theme (all core values + base semantic mappings)
2. for the alternate mode, emit only the semantic references that differ
3. core tokens are emitted once and shared across modes
This keeps the system smaller, more predictable, easier to validate, and less likely to drift.
> **Implementation:** See [Theme Provider](/docs/design/theme-provider) for how mode remapping is configured in ttoss themes.
---
## Summary
- A mode is a controlled variation of the same theme
- Core tokens are immutable — modes never change their values
- Modes remap semantic token references to different core tokens
- Semantic token names and meaning stay the same across modes
- Neutrals are usually the primary remapping lever
- Modes should stay minimal and diff-based
- Every mode must preserve accessibility and semantic pairings
---
## Quick Reference
Intent → token cheatsheet. Pick tokens fast here; read the family docs for the full contract.
This page is the single source for the intent → token mapping — the `@ttoss/fsl-theme` README links here rather than carrying its own copy. The one deliberate duplicate is the package's `llms.txt`, which ships the same mapping inside the npm tarball so agents have it offline.
> **Rule of thumb:** components consume **semantic** tokens only. If the token you need is not listed, check the family doc; if it still does not exist, open a [governance](./governance.md) request.
Grammar reminder:
- colors: `semantic.colors.{ux}.{role}.{dimension}.{state?}`
- `ux`: `action` \| `input` \| `navigation` \| `feedback` \| `informational`
- `role`: `primary` \| `secondary` \| `accent` \| `muted` \| `positive` \| `caution` \| `negative`
- `dimension`: `background` \| `border` \| `text`
- `state` (optional): `default` \| `hover` \| `active` \| `focused` \| `disabled` \| `selected` \| `pressed` \| `checked` \| `indeterminate` \| `expanded` \| `current` \| `visited` \| `droptarget` \| `invalid` (legality varies per `ux` — see [colors.md](./families/colors.md))
- everything else: `semantic.{family}.{group}.{step?}`
---
## Colors — by intent
| I want… | Token |
| :---------------------------------------------------------------------------------------------- | :------------------------------------------------------------------ |
| Primary button (filled, strongest CTA) | `semantic.colors.action.primary.{background,border,text}` |
| Secondary button (neutral chrome) | `semantic.colors.action.secondary.{background,border,text}` |
| Accent button (brand color, high emphasis) | `semantic.colors.action.accent.{background,border,text}` |
| Destructive button | `semantic.colors.action.negative.{background,border,text}` |
| Ghost / low-emphasis button | `semantic.colors.action.muted.{background,border,text}` |
| Text input (default) | `semantic.colors.input.primary.{background,border,text}` |
| Text input (error) | `semantic.colors.input.negative.{background,border,text}` |
| Text input (success / validated) | `semantic.colors.input.positive.{background,border,text}` |
| Text input (warning) | `semantic.colors.input.caution.{background,border,text}` |
| Nav link (default / current / visited) | `semantic.colors.navigation.primary.text.{default,current,visited}` |
| Toast / alert — neutral, no-valence status ("Auto-saved") | `semantic.colors.feedback.primary.{background,border,text}` |
| Toast / alert — informative (info / in-progress / new) | `semantic.colors.feedback.accent.{background,border,text}` |
| Toast / alert — success | `semantic.colors.feedback.positive.{background,border,text}` |
| Toast / alert — warning | `semantic.colors.feedback.caution.{background,border,text}` |
| Toast / alert — error | `semantic.colors.feedback.negative.{background,border,text}` |
| Page / content body text | `semantic.colors.informational.primary.text` |
| Muted / helper text | `semantic.colors.informational.muted.text` |
| Page background | `semantic.colors.informational.primary.background` |
| Divider line | `semantic.colors.informational.muted.border` |
| Focus ring color (system default — use when no `{ux}` applies) | `semantic.focus.ring.color` |
| Focus ring color (per-context — `{ux}` is `Action` / `Input` / `Navigation` / `Feedback`) | `semantic.colors.{ux}.{role}.border.focused` |
| Destructive ink on a part that paints no surface (quiet menu row / text action) | `semantic.consequence.destructive.ink` |
| Valence ink on a part that **reports** an outcome and paints no surface (status mark, summary) | `semantic.valence.{positive\|caution\|negative}.ink` |
| Unfilled part of a `ProgressBar`/`Meter`/`Slider` track (darkens in dark mode, unlike a border) | `semantic.rail.track` |
| Edge of a surface that **covers** content (popover, menu, tooltip, dialog, drawer, toast) | `semantic.overlay.outline` |
| Edge of a surface **in the flow** (card, panel, divider) | `semantic.colors.informational.{role}.border` |
Full grammar + role decision table: [Colors](./families/colors.md).
---
## Spacing — by intent
| I want… | Token |
| :---------------------------------------------------------------------------------- | :--------------------------------------------- |
| Padding inside a button/input | `semantic.spacing.inset.control.{sm,md,lg}` |
| Block (vertical) padding of a command trigger (CTA taller than generic controls) | `semantic.spacing.inset.action.block` |
| Padding inside a card/surface | `semantic.spacing.inset.surface.{sm,md,lg}` |
| Gutter inside an anchored surface or a row container (popover, menu, tooltip, list) | `semantic.spacing.inset.surface.xs` |
| Gap between stacked items (form fields) | `semantic.spacing.gap.stack.{xs,sm,md,lg,xl}` |
| Gap between inline items (icon + label) | `semantic.spacing.gap.inline.{xs,sm,md,lg,xl}` |
| Page horizontal gutter (responsive) | `semantic.spacing.gutter.page` |
| Section vertical gutter (responsive) | `semantic.spacing.gutter.section` |
| Minimum distance between hit targets | `semantic.spacing.separation.interactive.min` |
See [Spacing](./families/spacing.md).
---
## Sizing — by intent
| I want… | Token |
| :------------------------------------------------------------------------ | :--------------------------------------- |
| Hit target (min interactive floor) | `semantic.sizing.hit` |
| Glyph on the same line as text (button icon, chevron — resolves to `1em`) | `semantic.sizing.icon.text` |
| Standalone icon | `semantic.sizing.icon.{sm,md,lg}` |
| Avatar / identity chip | `semantic.sizing.identity.{sm,md,lg,xl}` |
| Paragraph max reading width | `semantic.sizing.measure.reading` |
| Surface (page shell / content column) max width | `semantic.sizing.surface.maxWidth` |
| Narrow standalone centered card (auth form, confirmation) | `semantic.sizing.surface.card` |
See [Sizing](./families/sizing.md).
---
## Typography — by intent
Token prefix: `semantic.text`.
| I want… | Token |
| :--------------------------------- | :---------------------------------- |
| Hero / marketing title | `semantic.text.display.{lg,md,sm}` |
| Page title / top-level headline | `semantic.text.headline.{lg,md,sm}` |
| Section / card title | `semantic.text.title.{lg,md,sm}` |
| Paragraph / body copy | `semantic.text.body.{lg,md,sm}` |
| UI label, form label, badge | `semantic.text.label.{lg,md,sm}` |
| Command trigger label (Button CTA) | `semantic.text.action.md` |
| Inline / block code | `semantic.text.code.{md,sm}` |
See [Typography](./families/typography.md).
---
## Borders, radii, elevation — by intent
| I want… | Token |
| :---------------------------------------------------- | :--------------------------------------------------------------------------- |
| 1px divider (width + style) | `semantic.border.divider.{width,style}` |
| Control outline (button, input) | `semantic.border.outline.control.{width,style}` |
| Surface outline (card) | `semantic.border.outline.surface.{width,style}` |
| Selected-state line | `semantic.border.outline.selected.{width,style}` |
| Focus ring (width + style + offset) | `semantic.focus.ring.{width,style,offset}` |
| Focus ring color | see [Borders § Which focus colour](./families/borders.md#which-focus-colour) |
| Command trigger / CTA radius (pill in the base theme) | `semantic.radii.action` |
| Control corner radius (inputs, utility triggers) | `semantic.radii.control` |
| Surface corner radius (cards, dialogs) | `semantic.radii.surface` |
| Pill / fully round | `semantic.radii.round` |
| Resting surface (no shadow) | `semantic.elevation.surface.flat` |
| Card shadow | `semantic.elevation.surface.raised` |
| Dropdown / popover shadow | `semantic.elevation.surface.overlay` |
| Modal / drawer shadow | `semantic.elevation.surface.blocking` |
See [Borders](./families/borders.md), [Radii](./families/radii.md), [Elevation](./families/elevation.md).
---
## Motion, opacity, z-index — by intent
| I want… | Token |
| :----------------------------------------- | :--------------------------------------------------- |
| Immediate UI feedback (hover, press) | `semantic.motion.feedback.{duration,easing}` |
| Element entering the screen | `semantic.motion.transition.enter.{duration,easing}` |
| Element leaving the screen | `semantic.motion.transition.exit.{duration,easing}` |
| Attention / emphasis animation | `semantic.motion.emphasis.{duration,easing}` |
| Decorative / ambient animation | `semantic.motion.decorative.{duration,easing}` |
| Scrim over content | `semantic.opacity.scrim` |
| Loading / in-progress dim | `semantic.opacity.loading` |
| Disabled dim | `semantic.opacity.disabled` |
| Document flow layer | `semantic.zIndex.layer.base` |
| Sticky header / toolbar | `semantic.zIndex.layer.sticky` |
| Dropdown / popover / tooltip | `semantic.zIndex.layer.overlay` |
| Modal / drawer (blocks interaction) | `semantic.zIndex.layer.blocking` |
| Toast / snackbar (transient, non-blocking) | `semantic.zIndex.layer.transient` |
See [Motion](./families/motion.md), [Opacity](./families/opacity.md), [Z-Index](./families/z-index.md).
---
## Data visualization — by intent
| I want… | Token |
| :--------------------------------- | :------------------------------------------------------------------ |
| Nth categorical series color | `semantic.dataviz.color.series.{1..8}` |
| Sequential (ordered) scale step | `semantic.dataviz.color.scale.sequential.{1..7}` |
| Diverging scale step | `semantic.dataviz.color.scale.diverging.{neg3..pos3}` |
| Reference line (target/baseline) | `semantic.dataviz.color.reference.{baseline,target}` |
| Highlighted / selected series | `semantic.dataviz.color.state.{highlight,selected}` |
| De-emphasized (context) series | `semantic.dataviz.color.state.muted` |
| Missing / not-applicable data | `semantic.dataviz.color.status.{missing,suppressed,notApplicable}` |
| Non-color differentiator — shape | `semantic.dataviz.encoding.shape.series.{1..8}` |
| Non-color differentiator — pattern | `semantic.dataviz.encoding.pattern.series.{1..6}` |
| Analytical stroke role | `semantic.dataviz.encoding.stroke.{reference,forecast,uncertainty}` |
See [Data Visualization](./data-visualization/index.md).
---
## If you can't find what you need
- **Token missing** → read the family doc; if still absent, open a governance request.
- **Want a raw value** → you need a new **semantic** token, not a core reference. Core is never consumed by components.
- **Repeating the same combo in many places** → extract a **component** or **pattern**, not a new token.
- **Building a chart** → start in [Data Visualization](./data-visualization/index.md), not in foundation colors.
---
## Theme Authoring
This document defines how to create and review themes in the ttoss design system.
It is not an API reference for `@ttoss/fsl-theme`. It is the design contract that should guide any theme before token values are implemented.
Use this document when you need to:
- create a new theme;
- review a built-in theme;
- adapt a brand into the FSL token model;
- decide whether a token value is coherent or not;
- explain why a theme feels dense, calm, technical, expressive, fragile, or robust;
- give an AI agent enough structure to author or review a theme without relying on visual taste alone.
A theme is not a collection of beautiful values.
A theme is the perceptual operating system of the interface: it governs how attention, action, meaning, risk, and time are distributed through token relationships.
---
## Relationship to other Design Token docs
This document sits above the individual token families.
It does not replace:
- **Token Model** — explains the `core` and `semantic` layers.
- **Modes** — explains how semantic references change across light, dark, and alternate modes.
- **Token families** — document the meaning of each token family.
- **Governance** — defines how token changes are proposed and approved.
- **Validation and Build** — defines how token rules are checked and emitted.
This document answers a different question:
> How should a theme be designed before values are chosen?
It owns two formal artifacts, and is the single source for both: the **Theme brief** (what a theme should feel like) and the **Formal Style Profile** (what it may and may not do, family by family). Style references, theme archetypes, and built-in themes publish profiles in that format and link back here for its definition.
---
## Core thesis
A good theme is not one where each token looks good in isolation.
A good theme is one where all token families reinforce the same product posture.
Spacing, sizing, typography, radii, color, border, elevation, focus, opacity, overlay, motion, and z-index must work as one language.
Each token decision should answer at least one of these questions:
| Question | Token families involved |
| ------------------------------------------------ | ------------------------------------- |
| What belongs together? | spacing, border, surface, typography |
| What is separate? | spacing, border, elevation, z-index |
| What can be acted on? | sizing, color, focus, motion |
| What matters most? | typography, color, spacing, elevation |
| What is safe, risky, successful, or unavailable? | color, opacity, focus, motion |
| What layer am I in? | surface, elevation, overlay, z-index |
| How much attention should this require? | color, motion, typography, spacing |
The theme is valid when these answers remain stable across components, screen sizes, density profiles, and color modes.
---
## Operating model
A theme should be understood as a layered system.
| Layer | In theme authoring |
| ------------------- | ----------------------------------------------------------------------------------- |
| Low-level values | Raw values: colors, spacing, radii, durations, shadows. |
| Semantic contract | The stable grammar through which components request meaning. |
| Design constitution | The rules that decide what meanings are legal and how conflicts are resolved. |
| Theme resolution | How values become mode-safe, state-safe, and component-consumable. |
| Validation | Contrast, state legality, pair compatibility, density safety, and mode correctness. |
| Components | Applications consuming semantic meaning. |
The design constitution is the kernel of the perceptual operating system.
Without it, a theme can still render. It just cannot govern itself.
---
## Decision hierarchy
When theme decisions conflict, use this order:
```txt
user safety
> accessibility
> semantic clarity
> interaction ergonomics
> information hierarchy
> product posture
> brand expression
> aesthetic novelty
```
A theme may be expressive, distinctive, or brand-heavy only after it remains accessible, legible, ergonomic, and semantically clear.
Brand may bend the surface. It may not break the contract.
---
## Theme brief
Every theme must start with a brief.
Do not start by choosing colors, radii, or spacing values. Start by defining the experience the theme should produce.
```yaml
theme:
name:
purpose:
primaryPosture:
secondaryPosture:
densityProfile:
readingMode:
pointerProfile:
interactionRisk:
surfaceModel:
brandEnergy:
accessibilityTarget:
colorModeStrategy:
platformBias:
```
### Allowed values
| Field | Values |
| --------------------- | ----------------------------------------------------------------------- |
| `primaryPosture` | `calm`, `productive`, `technical`, `expressive`, `editorial`, `premium` |
| `secondaryPosture` | optional; same values as `primaryPosture` |
| `densityProfile` | `compact`, `balanced`, `comfortable`, `spacious` |
| `readingMode` | `reading`, `operating`, `scanning`, `mixed` |
| `pointerProfile` | `fine`, `coarse`, `hybrid` |
| `interactionRisk` | `low`, `medium`, `high` |
| `surfaceModel` | `flat`, `lightly-layered`, `layered`, `immersive` |
| `brandEnergy` | `quiet`, `balanced`, `expressive` |
| `accessibilityTarget` | `AA`, `AA+`, `AAA-like` |
| `colorModeStrategy` | `light-only`, `dark-supported`, `dark-first`, `adaptive` |
| `platformBias` | `web`, `mobile`, `desktop`, `cross-platform` |
### Recommended base theme brief
The default built-in theme should optimize for modern product UI, not for a strong brand statement.
```yaml
theme:
name: base
purpose: default built-in foundation for modern product UI
primaryPosture: productive
secondaryPosture: calm
densityProfile: balanced
readingMode: mixed
pointerProfile: hybrid
interactionRisk: medium
surfaceModel: lightly-layered
brandEnergy: quiet
accessibilityTarget: AA+
colorModeStrategy: dark-supported
platformBias: web
```
The base theme should feel practical, calm, modern, trustworthy, and easy to extend.
It should not feel flashy, ornamental, cramped, fragile, or overly branded.
---
## Formal Style Profile
A Theme brief says what a theme should _feel_ like. A **Formal Style Profile** says what it may and may not _do_, family by family. It is the second formal artifact of theme authoring, and the shared format for every document that constrains token values: [style references](/docs/design/style-references) propose a profile, theme archetypes adopt one, and built-in themes implement one.
This section is the canonical definition of that format. A document that publishes a profile conforms to the schema below and links here rather than restating it.
### Axis: one section per token family
A profile is indexed by **token family** — the same families the [Token Model](./model.md) defines and the `families/` specs document. Not by mood, not by ad-hoc "posture" names: a family is the unit a theme actually sets values for, which is what makes a profile checkable against a real theme.
Cross-family concerns (contrast, depth, material feel) are expressed as constraints on the families that carry them — contrast under `colors`, depth under `elevation`, and so on — plus, where a rule genuinely spans families, a **Cross-family rules** section after the per-family ones.
Omit a family the profile does not constrain. Silence means "the base doctrine in this document applies unchanged", which is more useful than a row saying nothing.
### Levels
Every constraint carries exactly one of five levels. These are the only legal levels, and they mean:
| Level | Meaning | Conformance effect |
| --------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| **Required** | Must hold. A theme that violates it does not implement this profile, whatever else it does. | Violation = not conformant. |
| **Preferred** | The characteristic choice — what the profile looks like when followed with no competing pressure. | Departure needs a recorded reason. |
| **Tolerated** | Permitted without being characteristic. Available when product pressure justifies it; never the starting point. | Allowed; does not weaken conformance. |
| **Discouraged** | Works, but fights the profile's intent. Usually a symptom that the wrong profile was chosen. | Allowed under protest; accumulating these invalidates the fit. |
| **Forbidden** | Must not appear. Unlike Discouraged, this is a semantic or accessibility breach, not a matter of taste. | Violation = not conformant. |
`Required` and `Forbidden` are the conformance boundary — they are the two levels a reviewer or an agent can decide mechanically. `Preferred`, `Tolerated`, and `Discouraged` describe the gradient inside that boundary and always need judgement. Write a rule at the strongest level you can actually defend: a profile where everything is `Required` is a straitjacket, and one where everything is `Preferred` decides nothing.
### Shape
```md
### {n}. {Family}
**Posture:** one line — what this family is doing in service of the profile.
#### Required
- constraint
#### Preferred
- constraint
#### Forbidden
- constraint
```
### Conformance
A profile is only worth publishing if a theme can be checked against it. Every rule should be phrased so that a reviewer reading a theme's token values can answer yes or no. "Neutrals must dominate the general interface" is checkable; "the theme should feel refined" is not — that belongs in the brief.
Profiles do not create tokens. A profile constrains **core values, semantic mapping posture, allowed ranges, and mode tuning** — never token names. The prohibition on appearance-based public vocabulary ([Token Model](./model.md), invariant 5) holds inside every profile.
---
## Product posture
Product posture is the behavioral personality of the interface.
It is not a moodboard. It is a decision framework.
| Posture | Interface behavior | Typical use |
| ------------ | -------------------------------------------------------------------- | ---------------------------------------------------- |
| `calm` | Reduces noise, protects attention, uses soft hierarchy. | AI products, healthcare, productivity, focused work. |
| `productive` | Prioritizes speed, scanning, clear actions, and predictable rhythm. | SaaS, admin, dashboards, internal tools. |
| `technical` | Prioritizes precision, structure, compactness, and low ornament. | Devtools, infra, analytics, enterprise operations. |
| `expressive` | Uses stronger color, shape, motion, and brand presence. | Consumer products, marketing flows, onboarding. |
| `editorial` | Prioritizes reading rhythm, generous whitespace, and type hierarchy. | Docs, content, reports, knowledge products. |
| `premium` | Uses restraint, space, refined contrast, and slower rhythm. | Executive tools, high-touch brand experiences. |
A theme may combine two postures, but one must dominate.
Invalid:
```yaml
primaryPosture: modern
```
“Modern” is not operational. It does not tell the designer or implementation agent how to choose spacing, radii, motion, or color.
Valid:
```yaml
primaryPosture: productive
secondaryPosture: calm
```
This means the theme should support efficient work while avoiding unnecessary noise.
---
## Density
Density is the first geometric decision.
Density defines how much information and interaction fit into a given space. It affects visual rhythm, perceived speed, motor safety, and cognitive effort.
A theme must choose one density profile.
| Density | Meaning | Risk |
| ------------- | -------------------------------------------- | ----------------------------------------- |
| `compact` | High information density and tight rhythm. | Can become cramped or error-prone. |
| `balanced` | Efficient but comfortable product UI. | Can become generic without clear posture. |
| `comfortable` | More breathing room and slower rhythm. | Can feel less efficient for power users. |
| `spacious` | Strong focus, low density, large whitespace. | Can waste space in operational products. |
Density must not be applied as one global multiplier.
A compact theme should not simply shrink everything. A compact theme should reduce non-essential whitespace while preserving reading comfort and hit target safety.
### Density subdimensions
| Subdimension | Affects | Rule |
| ------------------- | ----------------------------------------------------- | -------------------------------------------------------- |
| Content density | Tables, lists, cards, stat groups. | May compress significantly. |
| Interaction density | Buttons, menus, toolbars, controls. | May compress visually, but hit targets must remain safe. |
| Reading density | Body text, descriptions, prose. | Should compress cautiously. |
| Decision density | Number and proximity of choices. | Must preserve decision clarity. |
| Signal density | Amount of color, iconography, badges, alerts, motion. | Must remain controlled. |
A good B2B product theme is often:
```txt
content dense
+ interaction safe
+ reading comfortable
+ signal restrained
```
---
## Geometry
Geometry is semantic.
Spacing and sizing are not just measurements. They communicate relationship, grouping, rhythm, hierarchy, and affordance.
### Spacing meaning
Spacing answers:
| Question | Meaning |
| -------------------------------------------- | ---------------------------- |
| Are these elements part of the same control? | Use the smallest inline gap. |
| Are these elements siblings in a group? | Use a sibling gap. |
| Did one group end and another begin? | Use a group gap. |
| Is this content inside a surface? | Use surface inset. |
| Is this a page boundary? | Use page gutter. |
| Are these independent targets? | Use interactive separation. |
The core rule:
```txt
the stronger the semantic relationship,
the smaller the space
```
This follows the Gestalt principle of proximity: elements near each other are perceived as related, while elements farther apart are perceived as separate.
### Spacing order rule
A theme should preserve this order:
```txt
icon-label gap
< inline sibling gap
< control inset
< stack sibling gap
< group gap
< section gap
< page gutter
```
Invalid:
```txt
icon-label gap = 16px
field-to-field gap = 12px
```
This makes an icon feel less related to its label than one field feels to another field.
Valid:
```txt
icon-label gap = 6px
field-to-field gap = 16px
section gap = 32px
```
### Spacing families
| Family | Design meaning |
| ------------------------------------ | ---------------------------------------------- |
| `spacing.inset.control` | Internal comfort of actionable controls. |
| `spacing.inset.surface` | Cognitive breathing room inside containers. |
| `spacing.gap.inline` | Horizontal belonging between related elements. |
| `spacing.gap.stack` | Vertical rhythm between sequential elements. |
| `spacing.gutter.page` | Relationship between viewport and content. |
| `spacing.gutter.section` | Relationship between large content regions. |
| `spacing.separation.interactive.min` | Motor safety between independent targets. |
### Spatial scale
A theme must define its base spatial unit.
Recommended:
```txt
baseUnit = 4px
```
Allowed for technical or highly dense themes:
```txt
baseUnit = 2px
```
A theme may use a hybrid scale:
```txt
micro: 2px increments
component: 4px increments
layout: 8px increments
```
But the hybrid model must be intentional and documented.
Use small increments for detail-level spacing and larger increments for layout rhythm.
---
## Sizing
Sizing is affordance.
Do not confuse visual size with interaction size.
| Size type | Meaning |
| ------------ | -------------------------------------- |
| Visual size | What the user sees. |
| Hit size | What the user can successfully target. |
| Content size | What the content requires. |
| Layout size | What the composition reserves. |
A theme must preserve this relationship:
```txt
icon size <= visual control size <= hit target size
```
Example:
```txt
icon = 16px
visual button = 32px
hit target = 40px or 44px
```
The visible object may be compact. The interactive affordance must remain safe.
### Sizing families
| Family | Design meaning |
| ------------------------- | -------------------------------------------------------- |
| `sizing.hit` | Probability of successful interaction. |
| `sizing.icon` | Symbol legibility and visual weight. |
| `sizing.identity` | Recognition of avatar, organization, product, or entity. |
| `sizing.measure.reading` | Comfortable line length for prose. |
| `sizing.surface.maxWidth` | Maximum useful composition width. |
| `sizing.viewport` | Relationship to device and viewport. |
### Hit target rule
A compact visual control may still need a larger invisible hit area.
This is especially important for:
- icon buttons;
- dense toolbars;
- table actions;
- mobile and coarse-pointer contexts;
- controls near destructive actions.
A theme fails if it makes small controls easier to see than to use.
---
## Typography
Typography defines voice, hierarchy, and rhythm.
It is not only text rendering.
| Role | Meaning |
| ---------- | ------------------------------------------------------ |
| `display` | Rare, high-emphasis narrative text. |
| `headline` | Page or section-level orientation. |
| `title` | Surface-level naming: card, dialog, panel, sheet. |
| `body` | Reading comfort and content rhythm. |
| `label` | Operational precision: controls, fields, badges, tabs. |
| `code` | Technical readability and alignment. |
The body text style is the center of the system. Spacing and vertical rhythm should be checked against body line-height.
### Typographic rhythm
A theme must define:
```txt
body font size
body line height
label size
title scale
heading scale
reading measure
```
Then spacing must reinforce the vertical rhythm.
Valid:
```txt
body.md line-height = 24px
stack.sm = 8px
stack.md = 16px
section gap = 32px
```
Invalid:
```txt
body.md line-height = 23px
all vertical spacing = unrelated arbitrary values
```
A theme does not need to use a strict baseline grid everywhere, but it must produce predictable rhythm.
### Reading measure
Long prose must have a maximum measure.
Recommended:
```txt
measure.reading = 45ch–75ch
```
Ordinary prose should not stretch across the full viewport.
This protects comprehension, scanning, and reading comfort.
---
## Shape and radii
Radius expresses material, posture, and affordance.
It is not decoration.
| Radius behavior | Meaning |
| --------------- | ---------------------------------------------- |
| Sharp | Technical, precise, dense, serious. |
| Mild | Neutral, productive, professional. |
| Soft | Friendly, calm, SaaS-like, assistive. |
| Round | Pill, avatar, chip, badge, contained identity. |
| Expressive | Brand-led, consumer, playful. |
A theme must define a shape grammar:
```txt
radii.control
radii.surface
radii.round
```
### Radius relationship rule
Default relationship:
```txt
control radius <= surface radius <= overlay radius
```
Exceptions are allowed only when intentional.
| Exception | Allowed when |
| ------------------ | ----------------------------------------------------------------------------- |
| Pill control | The component is a chip, tag, capsule, segmented item, or avatar-like object. |
| Sharp surface | The theme posture is technical or enterprise-strict. |
| Expressive overlay | The theme posture is consumer or brand-led. |
Invalid:
```txt
compact data table
+ huge rounded cells
+ tiny spacing
```
This combines a dense operational structure with a playful material signal.
---
## Surface model
Modern interfaces are layered environments.
A theme must define how each layer is represented.
| Layer | Function |
| --------- | --------------------------------------- |
| Page | Ambient background. |
| Surface | Contained content. |
| Raised | Locally emphasized content. |
| Overlay | Temporary floating content. |
| Blocking | Modal interruption. |
| Transient | Toast, notification, ephemeral message. |
### Layer distinction rule
A layer change should be communicated by at least two compatible signals.
Examples:
| Layer | Signals |
| ---------------- | ------------------------------------------------ |
| Raised card | Background shift + border or elevation. |
| Popover | Elevation + z-index + surface color. |
| Dialog | Scrim + elevation + z-index + focus containment. |
| Selected item | Background or border + text/icon state. |
| Disabled element | Semantic disabled color + interaction removal. |
Invalid:
```txt
only z-index changes,
but the visual layer remains identical
```
Invalid:
```txt
only shadow changes in dark mode,
where shadow is barely visible
```
---
## Dark mode
Dark mode is not inversion.
A dark theme must define a distinct surface model.
| Concern | Requirement |
| ------------------ | --------------------------------------------------------- |
| Page background | Deepest stable neutral. |
| Surface background | Slightly lifted neutral. |
| Raised surface | Tonal or border differentiation. |
| Overlay | Strong separation without excessive glow. |
| Text | Contrast preserved by pair registry. |
| Border | Visible enough to define structure without noise. |
| Shadow | May support depth, but must not be the only depth signal. |
A theme fails if dark mode is generated by simply swapping light and dark values.
A mode override must preserve semantic meaning. Only the resolved values should change.
---
## Color and signal
Color is not decoration.
Color communicates:
- UI kind;
- emphasis;
- valence;
- interaction state;
- foreground/background relationship;
- consequence.
FSL color grammar:
```txt
semantic.colors.{ux}.{role}.{dimension}.{state}
```
| Axis | Meaning |
| ----------- | ------------------------------------------ |
| `ux` | What kind of UI object this is. |
| `role` | What emphasis or valence it carries. |
| `dimension` | What part is being colored. |
| `state` | What interaction or system state it is in. |
### Pair rule
The atomic color unit is not a swatch.
The atomic color unit is a pair:
```txt
background + text
background + border
surface + focus
scrim + blocking surface
```
A theme must validate color as relationships, not isolated values.
Valid:
```txt
action.negative.background.default
+ action.negative.text.default
+ action.negative.border.default
```
Invalid:
```txt
red.500 is accessible
```
A swatch is not accessible by itself. A pair may be accessible or inaccessible.
### Signal exclusivity
One visual signal must not carry conflicting meanings.
Invalid:
| Color use | Conflict |
| ---------------------------------------------- | ------------------------------ |
| Red for destructive action and ordinary accent | Consequence vs brand emphasis. |
| Yellow for warning and selected state | Risk vs navigation state. |
| Muted gray for disabled and secondary action | Unavailable vs lower priority. |
| Accent for brand, focus, selected, and success | Brand vs system state. |
Valid:
| Signal | Meaning |
| -------- | ---------------------------------------------- |
| Negative | Error, destructive consequence, failure. |
| Caution | Risk, warning, needs attention. |
| Positive | Success, completion, safe state. |
| Accent | Brand pop or special emphasis, not validation. |
| Muted | Lower emphasis, not disabled by itself. |
---
## Accessibility floor
Accessibility is not a theme variant.
It is a floor.
Every theme must define and preserve:
| Requirement | Rule |
| ------------------ | ------------------------------------------------------------------ |
| Text contrast | Meets the declared contrast target. |
| Non-text contrast | Icons, borders, controls, and focus indicators remain perceivable. |
| Target size | Meets the declared pointer safety profile. |
| Focus visibility | Always visible and mode-safe. |
| Motion reduction | Motion can be reduced without losing meaning. |
| Text scaling | Layout tolerates larger text sizes. |
| Color independence | Meaning is not conveyed by color alone. |
Recommended default:
```txt
accessibilityTarget = AA+
```
`AA+` means the theme meets WCAG AA as a baseline and adds stricter internal expectations for focus visibility, dark mode, target safety, and mode-safe contrast.
Do not claim full WCAG conformance from theme tokens alone. Conformance depends on final implementation, content, and component behavior.
---
## Focus
Focus is navigation, not styling.
A theme must guarantee:
| Rule | Requirement |
| --------------- | ----------------------------------------------------------------- |
| Always visible | Every focusable element has a visible focus state. |
| Not color-only | Shape, outline, offset, or thickness must help communicate focus. |
| No layout shift | Focus must not move surrounding content. |
| Above hover | Keyboard focus must remain legible when hover also exists. |
| Mode-safe | Focus must work in light, dark, and high-contrast contexts. |
### State priority
When multiple states coexist, priority is:
```txt
disabled
> focus
> pressed / active
> selected / current
> hover
> default
```
Disabled removes interaction. Focus preserves navigation. Hover must never hide focus.
---
## Motion
Motion must express causality.
It should help users understand what changed, why it changed, and how it relates to their action.
| Motion family | Design meaning |
| ------------------------- | -------------------------------------------- |
| `motion.feedback` | Immediate response to user input. |
| `motion.emphasis` | Draws attention to meaningful change. |
| `motion.decorative` | Ambient polish; must be subtle and optional. |
| `motion.transition.enter` | New layer or object appears. |
| `motion.transition.exit` | Object leaves or interaction closes. |
### Motion restraint
A theme should follow:
```txt
feedback motion < transition motion < emphasis motion
```
In duration, not necessarily visual intensity.
Rules:
| Context | Motion behavior |
| ----------------- | -------------------------------------------------- |
| Button press | Fast and local. |
| Menu open | Fast, spatially grounded. |
| Dialog enter | Slightly slower, clear layer change. |
| Validation error | Noticeable but not theatrical. |
| Decorative effect | Lowest priority and disabled under reduced motion. |
Invalid:
```txt
decorative animation stronger than user feedback
```
Invalid:
```txt
modal transition so slow it blocks task flow
```
---
## Attention
Attention is a scarce resource.
A theme must define how much attention each signal is allowed to demand.
```txt
ambient < peripheral < explicit < interruptive < blocking
```
Not every state deserves the foreground.
Not every warning deserves a banner.
Not every update deserves motion.
Not every error deserves red.
Not every assistant action deserves a toast.
Use attention level as part of the theme’s signal grammar.
| Attention level | Meaning |
| --------------- | ----------------------------------------------- |
| `ambient` | Present but not actively calling for attention. |
| `peripheral` | Noticeable without interrupting the task. |
| `explicit` | Clearly visible and task-relevant. |
| `interruptive` | Temporarily redirects attention. |
| `blocking` | Stops progress until resolved. |
---
## Opacity
Opacity is auxiliary.
It must not replace semantic color.
Allowed:
| Token | Use |
| ------------------ | --------------------------------------------------------------- |
| `opacity.scrim` | Background dimming behind blocking surfaces. |
| `opacity.loading` | Temporarily reduced confidence during async work. |
| `opacity.disabled` | Media or decorative assets when semantic color is insufficient. |
Not allowed:
| Misuse | Reason |
| --------------------------------- | -------------------------------------------------- |
| Disabled text via opacity only | Contrast becomes unpredictable. |
| Disabled control via opacity only | State meaning is not explicit. |
| Muted hierarchy via opacity | Reduces legibility instead of expressing priority. |
| Hover via opacity | Often weak and inaccessible. |
A disabled state should be semantic first, opacity second.
---
## Borders and elevation
Borders define structure.
Elevation defines functional distance.
### Border
| Border type | Meaning |
| ---------------- | ------------------------------------------ |
| Divider | Separates content groups. |
| Surface outline | Defines container edge. |
| Control outline | Defines interactive boundary. |
| Selected outline | Marks persistent selection or currentness. |
Border color must come from semantic color tokens.
Border geometry must not carry semantic meaning alone.
### Elevation
| Elevation | Meaning |
| --------- | ------------------------------------- |
| Flat | Same plane as page or parent surface. |
| Raised | Locally grouped or emphasized. |
| Overlay | Temporarily floats above page flow. |
| Blocking | Interrupts and captures interaction. |
Elevation must align with surface color and z-index.
Invalid:
```txt
high shadow + base z-index
```
Invalid:
```txt
blocking z-index + flat visual treatment
```
---
## Theme derivation sequence
Create themes in this order:
| Order | Step | Output |
| ----: | ---------------------------- | ------------------------------------------------------ |
| 1 | Define posture | Behavioral personality. |
| 2 | Define density | Operational compactness. |
| 3 | Define accessibility target | Non-negotiable floor. |
| 4 | Define typography center | Body, label, title, line-height. |
| 5 | Define spatial unit | Micro, component, layout scale. |
| 6 | Define hit target model | Fine/coarse/hybrid interaction safety. |
| 7 | Define spacing relationships | Inset, gap, gutter, separation. |
| 8 | Define shape grammar | Control, surface, round. |
| 9 | Define surface model | Page, surface, overlay, blocking. |
| 10 | Define color roles and pairs | Text/background/border registry. |
| 11 | Define focus system | Ring, offset, color, priority. |
| 12 | Define attention levels | Ambient, peripheral, explicit, interruptive, blocking. |
| 13 | Define elevation and z-index | Layer distance and interaction capture. |
| 14 | Define motion | Feedback, emphasis, transition, decorative. |
| 15 | Validate invariants | Contrast, pairs, hierarchy, density, mode safety. |
Invalid process:
```txt
choose brand colors
then choose radius
then choose spacing values
then patch accessibility
```
Correct process:
```txt
define experience
then define relationships
then define values
then validate invariants
```
---
## Theme scorecard
Each theme should be reviewed across these axes.
Score each axis from `0` to `5`.
| Axis | 0 | 5 |
| ------------------ | --------------------------------- | -------------------------------------------------- |
| Posture clarity | No declared experience. | Clear operational posture. |
| Density coherence | Arbitrary compression. | Density applied by subdimension. |
| Spatial harmony | Values feel unrelated. | Relationships are predictable. |
| Typographic rhythm | Type and spacing conflict. | Type governs rhythm. |
| Ergonomic safety | Visual and hit size are confused. | Hit model is explicit. |
| Shape consistency | Radius used decoratively. | Radius expresses material. |
| Surface hierarchy | Layers are ambiguous. | Layers are visually and functionally clear. |
| Color semantics | Palette-led. | Pair-led and role-safe. |
| Attention control | Signals compete indiscriminately. | Signal intensity is proportional to task and risk. |
| Mode safety | Dark mode is inversion. | Each mode preserves meaning and contrast. |
| Accessibility | Patched late. | Built into invariants. |
| Agent-readiness | Requires taste judgment. | Rules are explicit and executable. |
A built-in theme should not be accepted unless every axis scores at least `4`.
---
## Validation rules
These rules should eventually be enforced by documentation review, tests, lint rules, or package validation.
| Rule ID | Rule |
| ------------------- | ------------------------------------------------------------- |
| `FSL-DESIGN-001` | Theme declares posture. |
| `FSL-DESIGN-002` | Theme declares density profile. |
| `FSL-DESIGN-003` | Theme declares accessibility target. |
| `FSL-GEO-001` | Spacing relationship order is preserved. |
| `FSL-GEO-002` | Hit target is not smaller than the declared safety floor. |
| `FSL-GEO-003` | Icon size is not treated as hit size. |
| `FSL-TYPE-001` | Type roles are functional, not tied to HTML tags. |
| `FSL-TYPE-002` | Reading measure is bounded. |
| `FSL-SHAPE-001` | Radius matches posture and density. |
| `FSL-SURFACE-001` | Layer change uses at least two compatible signals. |
| `FSL-SURFACE-002` | Dark mode is not simple inversion. |
| `FSL-COLOR-001` | Colors are validated as pairs, not swatches. |
| `FSL-COLOR-002` | Signal colors do not carry conflicting meanings. |
| `FSL-COLOR-003` | Text/background pairs meet declared contrast targets. |
| `FSL-FOCUS-001` | Focus is visible, mode-safe, and not hidden by hover. |
| `FSL-ATTENTION-001` | Signal intensity is proportional to task importance and risk. |
| `FSL-MOTION-001` | Motion expresses causality. |
| `FSL-MOTION-002` | Reduced motion does not remove meaning. |
| `FSL-OPACITY-001` | Opacity is not the primary disabled or text state. |
| `FSL-LAYER-001` | Elevation and z-index are semantically consistent. |
---
## AI authoring rules
When an AI assistant creates or reviews a theme, it must not start by generating token values.
It must follow this sequence:
```txt
1. Declare or infer the theme brief.
2. Define posture and density.
3. Derive typography center.
4. Derive spacing relationships.
5. Derive sizing and hit targets.
6. Derive shape grammar.
7. Derive surface model.
8. Derive color pair registry.
9. Derive attention levels.
10. Derive focus, elevation, opacity, and motion.
11. Validate invariants.
12. Only then emit or modify tokens.
```
If required information is missing, the assistant may proceed only by declaring explicit defaults.
| Missing input | Default |
| -------------------- | ---------------------------------------------------- |
| Posture | `productive` + `calm` |
| Density | `balanced` |
| Accessibility target | `AA+` |
| Color mode strategy | `dark-supported` only if dark pairs can be validated |
| Pointer profile | `hybrid` |
| Surface model | `lightly-layered` |
| Brand energy | `quiet` |
The assistant must not use vague visual goals such as “make it modern”, “make it nicer”, or “make it premium” without translating them into posture, density, geometry, signal, attention, and accessibility decisions.
---
## Anti-patterns
Avoid these patterns when creating or reviewing themes.
| Anti-pattern | Why it fails |
| ------------------------ | ---------------------------------------------------- |
| Palette-first theme | Starts with brand expression before UI function. |
| Density multiplier | Shrinks everything and breaks ergonomics. |
| Radius fashion | Applies trendy softness without posture logic. |
| Shadow-only hierarchy | Fails especially in dark mode. |
| Color-only state | Creates accessibility and semantic ambiguity. |
| Token value worship | Treats values as correct outside relationships. |
| Grid absolutism | Uses grid as substitute for spacing semantics. |
| Component-name tokens | Couples theme to implementation instead of meaning. |
| Inverted dark mode | Produces broken hierarchy and contrast. |
| Motion delight | Animates personality instead of causality. |
| Disabled opacity | Reduces contrast without guaranteeing state clarity. |
| Focus as decoration | Treats keyboard navigation as visual polish. |
| Attention inflation | Makes every signal compete for the foreground. |
| HTML typography coupling | Makes visual hierarchy depend on document tags. |
---
## Built-in theme acceptance checklist
Before a theme becomes built-in, verify:
- [ ] The theme has a completed theme brief.
- [ ] Posture and density are explicit.
- [ ] Typography defines a clear center of gravity.
- [ ] Spacing preserves relationship order.
- [ ] Hit targets are safe for the declared pointer profile.
- [ ] Radii match posture, density, and surface model.
- [ ] Color is validated through semantic pairs.
- [ ] Signal colors do not carry conflicting meanings.
- [ ] Attention levels are proportional to task importance and risk.
- [ ] Focus is visible in all supported modes.
- [ ] Dark mode has its own surface model.
- [ ] Elevation, surface, overlay, and z-index agree.
- [ ] Motion communicates causality and supports reduced motion.
- [ ] Opacity is not used as the primary semantic state.
- [ ] The theme passes the review scorecard.
- [ ] The theme can be explained without relying on subjective taste.
---
## Final doctrine
The ten laws of FSL theme authoring:
1. Values are not design. Relationships are design.
2. A theme must declare posture before tokens.
3. Density is operational, not aesthetic.
4. Spacing communicates relationship.
5. Sizing communicates affordance.
6. Typography governs rhythm.
7. Radius expresses material.
8. Color communicates meaning only through valid pairs.
9. Attention is scarce; focus, contrast, target size, and reduced motion are constitutional floors.
10. A theme is finished only when its rules are executable by humans, agents, and validators.
A theme is valid when:
```txt
its core values form a coherent perceptual scale;
its semantic tokens express stable design intent;
its families reinforce one another;
its modes preserve meaning and accessibility;
its density matches product posture;
its geometry communicates relationship;
its signals remain exclusive and legible;
its attention levels are proportional to task and risk;
and its rules can be validated without relying on taste.
```
A theme is excellent when it disappears as decoration and remains as orientation.
---
## References
- [The Missing Layer in Design Systems: Semantic Contract](/blog/2026/03/09/the-missing-layer-in-design-systems-semantic-contract)
- [Tazuna UX](/blog/2026/03/09/tazuna-ux)
- [Design Tokens Community Group — Format Module](https://www.designtokens.org/TR/2025.10/format/)
- [Nielsen Norman Group — Proximity Principle in Visual Design](https://www.nngroup.com/articles/gestalt-proximity/)
- [Nielsen Norman Group — 5 Principles of Visual Design in UX](https://www.nngroup.com/articles/principles-visual-design/)
- [Material Design 3 — Spacing](https://m3.material.io/foundations/layout/grids-spacing/spacing)
- [Material Design 3 — Density](https://m3.material.io/foundations/layout/grids-spacing/density)
- [Material Design 3 — Color roles](https://m3.material.io/styles/color/roles)
- [Carbon Design System — Spacing](https://carbondesignsystem.com/elements/spacing/overview/)
- [IBM Design Language — 2x Grid](https://www.ibm.com/design/language/2x-grid/)
- [Fluent 2 — Layout](https://fluent2.microsoft.design/layout)
- [Fluent 2 — Typography](https://fluent2.microsoft.design/typography)
- [W3C — WCAG 2.2](https://www.w3.org/TR/WCAG22/)
- [OpenAI — Evaluation best practices](https://developers.openai.com/api/docs/guides/evaluation-best-practices)
- [Anthropic — Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
---
## Validation and Build
Validation protects the semantic contract.
Build distributes that contract without changing its meaning.
This document defines:
- what must always be validated
- where validation rules live
- how validation severity works
- what build and output must guarantee
It does **not** define every rule for every token family.
Family-specific validations belong in each family documentation.
Pattern and application validations belong above the token layer.
## Source of truth
The token source is the only place where tokens are created, changed, deprecated, or removed.
Generated files are build artifacts.
They must not be edited manually.
## Scope
Validation exists at three levels:
### Global validation
Global validation protects the architecture of the system.
It enforces rules that must remain true across all token families.
### Family validation
Family validation protects the local contract of a token family.
Family docs are the normative source of these rules.
They may define only what is specific to that family, such as:
- grammar
- legal combinations
- required semantic pairings
- family invariants
- family-specific warnings
- family-specific output expectations
The central validation model does not redefine these rules.
It requires that they exist where needed and that they remain enforceable.
### Output validation
Output validation protects the generated contract.
It exists because a valid token source is not enough if build output breaks meaning.
Pattern and application concerns are outside the token validator.
## Global validation
### Structural validation
Structural validation protects the token graph.
It must guarantee:
- unique token names
- valid references
- resolvable references
- no circular references
If the token graph is invalid, validation must fail before build.
Deprecation and replacement metadata are governed by [governance](./governance.md) but not yet machine-enforced — no deprecated token has ever shipped, and the enforcement lands with the first one (evidence rule).
### Semantic contract validation
Semantic contract validation protects the architecture of the system.
It must guarantee:
- semantic tokens remain the public API
- core tokens remain value-only
- semantic tokens remain meaning-first
- UI does not consume core tokens directly
- semantic meaning does not change silently
- no parallel vocabulary is introduced
- naming expresses meaning, not appearance, component, mode, chart type, or library behavior
The change policy these guarantees enforce — when meaning may change and how — is defined in [Governance](./governance.md).
### Cross-family validation
Some guarantees depend on more than one family.
Use cross-family validation only when required by the contract, such as:
- readability and perceivability
- interactive ergonomics
- focus visibility across geometry and color
- mode correctness across semantic pairings
- preserving distinction between families whose meanings must not collapse into each other
Cross-family validation exists to protect composed guarantees.
It must not become a proxy for subjective design review.
## Build and output
Build must preserve the contract.
At minimum, build and output validation must guarantee:
- build runs only from validated source
- generated files are derived from source, not treated as source
- generated output does not invent new semantics
- generated output does not contain broken references
- semantic token names remain stable where they are the public API
- themes and modes preserve semantic meaning
- each supported mode remains valid after build
- capability-specific output preserves the same contract
- output remains consistent with governance and versioning rules
Build may transform syntax, format, and platform representation.
It must not change meaning.
## Severity
Validation uses three severities.
### Error
An `error` blocks merge.
Use `error` when the issue breaks:
- the token graph
- the semantic contract
- an explicit family invariant
- an explicit accessibility requirement
- build correctness
- output correctness
Errors protect guarantees.
### Warning
A `warning` does not block merge by default.
Use `warning` when the contract still holds but quality is weakened, such as:
- semantic drift risk
- reduced consistency
- weaker clarity
- fragile usability
- higher long-term maintenance cost
Warnings protect system quality without turning validation into a style police tool.
### Info
`info` is a non-blocking signal.
Use it for guidance only.
### Severity rule
- `error` must be objective and testable
- `warning` must not encode subjective preference
- `info` must not affect correctness
## Accessibility ownership
Tokens validate **pre-conditions**, not final accessibility compliance.
Accessible UI requires validation at three levels, each with distinct ownership:
| Level | Validates | Examples |
| :-------------------------- | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Token layer** | Pre-conditions | Contrast-safe palette pairs, minimum hit target sizes, reduced-motion token support, focus ring width ≥ 2px |
| **Component/pattern layer** | Composition | Focus appearance (area + contrast together), target size OR sufficient spacing, color-not-alone for meaning, border + color pairing for selected states |
| **Final output** | Rendering | Actual computed contrast ratios, actual focus ring visibility in context, actual target geometry on device |
Token validation guarantees that the **building blocks** are accessible.
It does not guarantee that **composed UI** is accessible.
Components, patterns, and final output must validate their own accessibility obligations.
> Treating token-level accessibility as sufficient creates a false sense of compliance.
> Each layer owns its part of the contract.
## Semantic diff
Changes to the token system must be classifiable by their semantic impact.
The following rules define how to evaluate a token change objectively:
### Structural equivalence vs. resolved equivalence
- **Structural equivalence**: two tokens have the same shape and reference structure, but may resolve to different values. A structural change (e.g., remapping `action.primary.background.default` from `brand.500` to `brand.400`) is valid when meaning stays the same.
- **Resolved equivalence**: two tokens resolve to the same final value. Detecting this helps identify redundancy and potential parallel vocabulary.
### Change classification
Every change is classified by its version impact per [Governance — Versioning](./governance.md#versioning). Structural equivalence identifies mapping changes; anything beyond a meaning-preserving remap follows the deprecation and versioning policy defined there.
### Collision detection
A collision occurs when:
- two tokens in the same namespace resolve to the same final value **and** serve the same semantic role → one should be removed
- a new token introduces a name that expresses the same meaning as an existing token → parallel vocabulary violation
### Deprecation manifest
Deprecation metadata requirements are defined in [Governance — Deprecation](./governance.md#deprecation). Validation checks that the required fields are present.
> Semantic diff rules that require semantic judgment (e.g., "does this name express the same meaning?") require human review. Only structural and resolved equivalence checks are fully automatable.
## Merge rule
A token change is valid only when all of the following are true:
- structural validation passes
- semantic contract validation passes
- all applicable family errors pass
- required cross-family validation passes
- build succeeds
- output validation passes
- version impact is understood
Warnings must be visible and reviewable.
They do not block merge by default unless a stricter policy is adopted intentionally.
## Principle
Validate only what is necessary for the contract, objectively testable, and enforceable in CI.
Keep global validation focused on architecture.
Keep family validation focused on local contract.
Keep output validation focused on preserving meaning after build.
The system stays scalable when validation is explicit, bounded, enforceable, and aligned with the semantic contract.
---
## 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 {#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.
| Term | Meaning | Distinguish from |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Action** | An 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). |
| **Input** | An interactive entity whose primary meaning is entering, editing, or manipulating a value directly. | Not **Selection** (choosing among options), not **Action** (performing an operation). |
| **Selection** | An 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. |
| **Collection** | An 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. |
| **Overlay** | An entity whose primary meaning is temporary layered presentation above the base interface. | Not **Disclosure**; Disclosure reveals in place, Overlay creates a layered interaction context. |
| **Navigation** | An 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. |
| **Disclosure** | An 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. |
| **Feedback** | An 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. |
| **Structure** | An 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 {#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.
| Term | Meaning | Distinguish from |
| --------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **root** | The primary semantic container of an entity as a whole. | Not just “outer DOM node”; root is the semantic whole of the entity. |
| **control** | The 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. |
| **surface** | A semantically meaningful containing plane or container that holds content or interaction. | Not **content**; surface is the containing support, content is what is carried. |
| **content** | The main carried content of an entity or composite. | Not **body** in all cases; body is a specific text/content role, content is broader. |
| **label** | A 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. |
| **description** | A supporting explanatory part that clarifies meaning, conditions, or usage. | Not **status**; description explains, status communicates current condition/outcome. |
| **title** | A 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. |
| **body** | The primary explanatory or descriptive content body of an entity or surface. | Not **content** in general; body is a specific textual/content-bearing role. |
| **actions** | A grouped area or region that contains one or more action-bearing parts. | Not a single action itself. |
| **status** | A part whose function is to communicate condition, progress, success, warning, or error. | Not **description**; status is current condition, description is explanatory support. |
| **icon** | A compact symbolic or pictorial supporting part. | Not **indicator**; icon may identify or decorate, indicator signals state or choice. |
| **indicator** | A part whose role is to signal state, selection, or position. | Not **icon** in general; indicator has a signaling function. |
| **item** | A member unit inside a collection or grouped set. | Not **content** in general; item implies membership in a set. |
| **trigger** | A 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. |
| **backdrop** | A layered part positioned between an overlayed structure and the obscured underlying interface. | Not **surface**; backdrop is environmental/layering support, not primary carried surface. |
| **positioner** | A part whose role is to place or anchor another layered structure spatially. | Not generic layout; it is specifically for semantic positioning of another structure. |
| **closeTrigger** | A trigger whose role is specifically to close or dismiss the current entity. | Not every dismiss action; this is specifically a trigger part. |
| **supportingVisual** | A non-primary visual part that supports recognition, context, or grouping. | Not **media** in general; supportingVisual is subordinate and usually lighter-weight. |
| **trailingMeta** | A secondary trailing part that carries supporting metadata or contextual detail. | Not **status**; metadata is not necessarily current state. |
| **selectionControl** | A structural part whose immediate role is selection or toggle operation within a larger entity. | Not generic **control**; this specifically participates in selection semantics. |
| **media** | A part whose role is carrying image, video, illustration, or rich visual media. | Not **icon**; media is richer and semantically broader. |
| **leadingAdornment** | A 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. |
| **trailingAdornment** | A supporting part positioned after the primary control, carrying a visual cue, suffix, or affordance. | Not **control**; this part is subordinate and contextual. |
| **validationMessage** | A 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 {#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.
| Term | Meaning | Distinguish from |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| **command** | An interaction that issues an operation or command without primarily representing navigation, value entry, or selection. | Not **navigate.link**, not **entry.text**, not **select.single**. |
| **confirm** | An interaction that explicitly affirms, commits, or accepts a pending operation or state transition. | Not generic **command**; confirm is a committing subtype of action. |
| **dismiss** | An interaction that closes, cancels, exits, or retreats from the current interaction path. | Not **secondary** or **muted**; dismiss is not an emphasis level. |
| **entry.text** | An interaction centered on entering or editing free-form text. | Not **entry.value** in general; text is one subtype of value entry. |
| **entry.value** | An interaction centered on entering or manipulating a value, not necessarily text. | Broader than **entry.text**. |
| **select.single** | An interaction that chooses exactly one option from a set. | Not **select.multi** or **toggle.binary**. |
| **select.multi** | An interaction that chooses more than one option from a set. | Not **select.single**. |
| **toggle.binary** | An interaction that switches between two discrete states. | Not **toggle.tristate**. |
| **toggle.tristate** | An interaction that can lawfully occupy three states, including an indeterminate or partial state. | Not **toggle.binary**. |
| **navigate.link** | An interaction whose primary function is movement to another destination or location. | Not **command**; even if visually button-like, its semantic core is navigation. |
| **navigate.step** | An interaction whose function is progression between stages, screens, or ordered steps. | Not general navigation across arbitrary destinations. |
| **disclose.toggle** | An interaction that reveals or hides related content in place. | Not an overlay entity's open/close — that is modeled at the Entity layer. |
| **status.passive** | A communicative condition that informs without demanding immediate user action. | Not **status.interruptive**. |
| **status.interruptive** | A 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 were **removed** from the core (see §10.14) — popup semantics live in projection profiles, expressed via `disclose.toggle` plus an independent Entity expression for the revealed surface.
---
## 4. Composition Role {#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.
| Term | Meaning | Distinguish from |
| ------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **primaryAction** | The main forward, commit, or preferred action path within a composition. | Not **Action** itself; this is a compositional role, not an entity kind. |
| **secondaryAction** | A subordinate but still intentional action path within a composition. | Not **dismissAction**; secondary is not necessarily exit/cancel. |
| **dismissAction** | An action whose role is to cancel, close, back out, or safely dismiss the current flow. | Not generic **secondaryAction**; dismiss is semantically specific. |
| **heading** | A compositional role introducing the primary heading of a larger unit. | Not generic **title** in every context; this is relational to a composition. |
| **body** | A 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. |
| **status** | A 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. |
| **control** | A 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. |
| **label** | A compositional role designating where a naming/label child belongs. | Not the same as `label` Structural Role; in Composition, this names the parent-side slot. |
| **description** | A compositional role designating where a descriptive child belongs. | Not the same as `description` Structural Role; in Composition, this names the parent-side slot. |
| **supporting** | A compositional role designating where a supporting child belongs. | Broader than specific label/description/status slots. |
| **selection** | A 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 {#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.
| Class | Term | Meaning | Distinguish from |
| -------- | ------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Emphasis | **primary** | The main intended emphasis in a semantic context. | Not “blue”, “bold”, or any visual style. |
| Emphasis | **secondary** | A secondary but still intentional emphasis relative to the same context. | Not equivalent to dismiss, muted, or less important in every case. |
| Emphasis | **accent** | A deliberately differentiated emphasis used to highlight meaningful distinction from the default emphasis. | Not just “more colorful”; accent is semantic divergence. |
| Emphasis | **muted** | A de-emphasized but still meaningful evaluation. | Not “disabled”, not “inactive”, not “secondary” in general. |
| Valence | **positive** | An affirming, successful, healthy, or favorable evaluation. | Not the same as “success UI token”; this is foundational meaning. |
| Valence | **caution** | A warning or careful-attention evaluation. | Not the same as “negative”; caution signals risk, not necessarily harmful outcome. |
| Valence | **negative** | A harmful, erroneous, destructive, or adverse evaluation. | Not necessarily **destructive** consequence; evaluation and consequence are distinct dimensions. |
### Critical disambiguations
- **negative** ≠ **destructive**
`negative` is evaluative.
`destructive` is consequential.
- **muted** ≠ **disabled**
`muted` still carries meaning.
`disabled` is a state.
---
## 6. Consequence {#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.
| Term | Meaning | Distinguish from |
| ----------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **neutral** | No special consequence or risk profile is implied beyond the baseline interaction. | Not the absence of semantics; simply no special risk-bearing consequence. |
| **reversible** | The effect can be undone or reverted without major loss. | Not the same as `recoverable`; reversible means the original change itself can be undone. |
| **committing** | The interaction moves the user or system into a more committed state. | Not every primary action is committing. |
| **destructive** | The interaction causes deletion, invalidation, or materially harmful loss. | Not the same as `negative` in general. |
| **interruptive** | The interaction or condition interrupts flow and demands immediate or prioritized handling. | Not every warning is interruptive. |
| **recoverable** | A failure or adverse path exists, but recovery is expected to be supported. | Not the same as `reversible`; recoverable may involve repair, not simple undo. |
| **safeDefaultRequired** | The 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 projection profile may codify a narrower subset of this vocabulary when the
broader terms collapse into one of the narrower ones or into another dimension.
A narrowing is lawful only when it is declared and justified, term by term, in
the profile's own artifact — and it binds that profile, not FSL: a different
profile may codify more of the vocabulary if its prototypes create new
distinctions. The shipped component profile narrows this dimension to three
values; its declaration and rationale live in the
[Component Model — Consequence](/docs/design/design-system/components/component-model#consequence).
---
## 7. State {#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.
| Term | Meaning | Distinguish from |
| ----------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| **default** | The baseline state in the absence of another active state. | Not “normal looking”; it is the unmodified semantic base state. |
| **hover** | A pointer-proximity state indicating hover-capable engagement. | Not `focused`; hover is not keyboard focus. |
| **active** | A currently engaged action state, often during direct interaction. | Not `selected` or `pressed` in all cases. |
| **focused** | A state indicating current input or interaction focus. | Not `hover`. |
| **disabled** | A state indicating the entity is unavailable for normal interaction. | Not `muted`; disabled is availability, not emphasis. |
| **selected** | A state indicating inclusion or chosen membership in a set. | Not always `checked`; selection and checkedness are related but not identical universally. |
| **pressed** | A state indicating active pressed engagement, often in command/toggle controls. | Not always persistent like `selected`. |
| **checked** | A state indicating affirmative selection or toggle-on condition in applicable interaction kinds. | Not `selected` in every interaction model. |
| **indeterminate** | A state indicating partial, mixed, or unresolved condition in a tri-state model. | Not a visual ambiguity; it is a lawful third semantic state. |
| **expanded** | A state indicating disclosed or expanded content/structure. | Not `selected`; expansion is visibility structure. |
| **current** | A state indicating the current item, location, or active point in a navigational or ordered structure. | Not simply selected. |
| **visited** | A state indicating prior navigation visitation where such history is semantically meaningful. | Not available for all interaction kinds. |
| **droptarget** | A state indicating that the entity is currently a relevant target for drop-based interaction. | Not generic active state. |
| **invalid** | A runtime state indicating the entity's current value failed validation. | Not **negative** (Evaluation) — invalid is a runtime outcome of the user's data, never an authorial valence choice. |
### 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.
- `invalid` only makes sense where validation semantics apply (value entry and selection).
---
## 8. Layer Role {#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.
| Term | Meaning | Distinguish from |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **base** | The ordinary baseline layer of the interface. | Not `raised` or `overlay`. |
| **sticky** | A persistent elevated-presence layer that remains attached to the base interaction context while retaining privileged visibility. | Not full overlay behavior. |
| **raised** | A higher-emphasis surface or layer relative to the base, without necessarily becoming an overlay. | Not the same as `overlay`. |
| **overlay** | A layered role above the base interface that creates clear semantic separation. | Not necessarily `blocking`. |
| **blocking** | A layer role that not only overlays but also semantically blocks or captures interaction from the obscured context. | Stronger than `overlay`. |
| **transient** | A 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 {#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.
| Term | Meaning | Distinguish from |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| **composition** | Context arising from semantic placement inside a larger composite structure. | Not environment or platform condition. |
| **environment** | Context arising from the surrounding operating situation of the interface. | Broader than direct interaction mechanics. |
| **interactionEnvironment** | Context arising from the conditions of interaction itself, such as device or input modality constraints relevant to interaction behavior. | Narrower than general environment. |
| **mode** | Context arising from a global or local semantic mode of operation. | Not simply theme or styling mode. |
| **density** | Context arising from semantic compactness or spaciousness of interaction/content arrangement. | Not just spacing values; this is contextual interpretation. |
| **accessibilityPreference** | Context arising from explicit accessibility-related user preference or need. | Not generic environment. |
| **platformCondition** | Context 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 [Structural Language §3.1](./fsl-structural-language.md) ("Structure must remain smaller than projections") and rule 1 of §12 below ("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.
---
### 10.15 invalid vs negative
- **invalid** is a State — the runtime outcome of validating the user's data.
- **negative** is an Evaluation — authorial valence chosen when the expression is written.
A control becomes `invalid` because of what the user entered; it is voiced `negative` because of what the author meant. Expressing validation by re-voicing the control (`evaluation: negative`) is a category mistake: state lives in the user's data, evaluation lives in the author's pen. Adjacent display parts (a validationMessage) lawfully carry `negative` valence _about_ the invalid state. Mirrors §10.5 (`negative` ≠ `destructive`) and §10.6 (`muted` ≠ `disabled`).
---
## 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.
---
## FSL Structural Language
> **The FSL Structural Language defines how foundational semantic concepts are combined into valid, governed, machine-usable semantic expressions.**
>
> It is the formal structure that sits between the **FSL Lexicon** and all **derived semantic systems**.
This document is normative.
It defines:
- the structural dimensions of the language
- the canonical shape of semantic expressions
- normalization rules
- legality rules
- contextual refinement rules
- the interface boundary to downstream projections
- conformance requirements
It does **not** define:
- the full dictionary of core concepts
- component APIs
- token-family grammars
- theme values
- runtime implementation
Those belong to other artifacts.
---
# 1. Purpose
The purpose of the FSL Structural Language is to make the FSL Lexicon usable as a real language.
The Lexicon defines:
- what the terms mean
The Structural Language defines:
- how terms can be combined
- what combinations are valid
- what combinations are invalid
- what context may refine
- what downstream systems may derive
Without the Structural Language, the Lexicon is a dictionary without syntax.
Without the Lexicon, the Structural Language is a syntax without meaning.
Both are required.
---
# 2. Role in the architecture
The semantic architecture is composed of five layers:
1. **FSL Lexicon**
The dictionary of foundational concepts.
2. **FSL Structural Language**
The formal structure of valid semantic expressions.
3. **Component Semantics Projection**
The component model derived from FSL. Specified by the [Component Model](/docs/design/design-system/components/component-model).
4. **Semantic Token Projection**
The semantic token model derived from FSL. Specified by the [design tokens documentation](/docs/design/design-system/design-tokens/model).
5. **Resolution contract**
The obligation that every resolution function (validate, normalize, resolve, project, explain) has a declared owner. Defined in §14.
This document defines only layer 2. It defines structure, not delivery state — the implementation status of each layer is tracked in the [FSL overview](./index.md).
---
# 3. Design principles
## 3.1 Structure must remain smaller than projections
The Structural Language must remain minimal.
Anything that exists only because a downstream system needs it belongs in a projection profile, not here.
## 3.2 Every dimension must answer a distinct question
Dimensions must be orthogonal.
If two dimensions answer the same semantic question, one of them is wrong or redundant.
## 3.3 The language must support composition
The meaning of a valid expression must come from:
- the meanings of its constituent terms
- the structure that combines them
- lawful context refinement only
## 3.4 Context refines; it does not redefine
Context may narrow or specialize meaning, but it may not replace foundational identity.
## 3.5 Structural legality is part of the language
Validity is not a downstream implementation heuristic.
It is part of the language itself.
## 3.6 Projections are derived, not foundational
Component semantics and token semantics must derive from this structure.
They must not define their own incompatible language.
## 3.7 Composition names structural slots
The Composition dimension deliberately reuses Structural Role names (`label`, `description`, `status`, `control`, `body`, `selection`, and others) as **slot designators** — the parent-side name of the position where a structurally-typed part belongs.
This is a design choice, not a disjointness violation. A term like `label` in the Structural Role dimension describes a part's own topology; the same term in the Composition dimension designates the slot that part occupies in a larger whole. The dimension carries the distinction; the shared name carries the correspondence between a part and the slot it fills. See §11.3 for the formal disjointness rule.
---
# 4. Semantic strata
The Structural Language recognizes two strata.
## 4.1 Foundational stratum
The foundational stratum contains semantic dimensions that exist before:
- component APIs
- token grammars
- theme systems
- styling engines
These dimensions are the true core of the language.
## 4.2 Projection stratum
The projection stratum contains semantic forms needed by downstream systems.
Examples:
- token-family-specific semantic domains
- text-scale grammars
- spacing contracts
- size contracts
These are governed by FSL but are **not** part of the foundational structure defined here.
This document covers only the foundational stratum and its projection interfaces.
---
# 5. Foundational structural dimensions
The Structural Language defines the following structural dimensions.
The actual vocabulary of each dimension lives in the **FSL Lexicon**.
This document defines their structural role in the language.
## 5.1 Entity
**Question answered:** What kind of interactive thing is this?
The semantic identity of the thing.
**Vocabulary:** [Lexicon §1 — Entity Kind](./fsl-lexicon.md#1-entity-kind) (the normative registry; this document never re-enumerates it).
Entity is the strongest identity dimension.
It must not be redefined by context.
:::note Name collision with the Structure dimension
The Entity Kind `Structure` (capitalized) is distinct from the Structural Role dimension (§5.2) which uses lowercase `structure` as its field name in the canonical expression. See Lexicon §10.12 for the full disambiguation.
:::
---
## 5.2 Structure
**Question answered:** What structural function does this part play?
The semantic topology of the thing or part.
**Vocabulary:** [Lexicon §2 — Structural Role](./fsl-lexicon.md#2-structural-role).
Structure describes part function, not identity.
---
## 5.3 Interaction
**Question answered:** What kind of interaction is being expressed?
Interaction describes the mode of user-system semantic operation.
**Vocabulary:** [Lexicon §3 — Interaction Kind](./fsl-lexicon.md#3-interaction-kind).
> `popup.*` composite terms (listbox/grid/tree/dialog) are intentionally **not** foundational — they belong to the Web/ARIA Projection Profile. The trigger carries `disclose.toggle`; the revealed surface is modeled as its own Entity expression. See FSL Lexicon §10.14.
Interaction is a foundational dimension because real interface structures cannot be disambiguated safely from identity and structure alone. (A profile may still defer codifying it — see §13.3.)
---
## 5.4 Composition
**Question answered:** What role does this thing play within a larger composition?
Composition expresses relational semantics.
**Vocabulary:** [Lexicon §4 — Composition Role](./fsl-lexicon.md#4-composition-role).
Composition refines meaning relationally.
It does not replace entity identity.
---
## 5.5 Evaluation
**Question answered:** What evaluative or emphatic meaning is carried?
Evaluation expresses semantic emphasis or valence.
**Vocabulary:** [Lexicon §5 — Evaluation](./fsl-lexicon.md#5-evaluation) (a discriminated union of emphasis and valence — an expression carries one class or the other, never both).
Evaluation is foundational because meaning like “negative” or “muted” must exist before token color or visual realization is chosen.
---
## 5.6 Consequence
**Question answered:** What user-facing consequence or risk profile is carried?
Consequence expresses interaction-critical semantics such as risk, reversibility, or interruption.
**Vocabulary:** [Lexicon §6 — Consequence](./fsl-lexicon.md#6-consequence).
Consequence exists because some semantics materially shape interaction design and user experience while remaining deeper than styling.
---
## 5.7 State
**Question answered:** What semantic or interactional state is active?
**Vocabulary:** [Lexicon §7 — State](./fsl-lexicon.md#7-state).
State is governed by legality.
Not every state is legal for every interaction type.
---
## 5.8 Layer
**Question answered:** What semantic layer role does this thing occupy?
**Vocabulary:** [Lexicon §8 — Layer Role](./fsl-lexicon.md#8-layer-role).
Layer is semantic layering, not raw z-index.
---
## 5.9 Context
**Question answered:** What lawful contextual refinements are active?
Context is a controlled refinement dimension.
**Vocabulary:** [Lexicon §9 — Context Class](./fsl-lexicon.md#9-context-class).
Context may refine meaning but must not redefine foundational identity.
---
# 6. Canonical semantic expression
The foundational language is expressed through a canonical semantic expression.
## 6.1 Canonical form
```txt id="1x1udm"
SemanticExpression = {
entity: EntityTerm,
structure: StructureTerm,
interaction?: InteractionTerm,
composition?: CompositionTerm,
evaluation?: EvaluationTerm,
consequence?: ConsequenceTerm,
state?: StateTerm,
layer?: LayerTerm,
context?: ContextRefinementSet
}
```
## 6.2 Required dimensions
Every valid semantic expression must contain:
- `entity`
- `structure`
All other dimensions are optional by form, but only legal when semantically meaningful.
## 6.3 Optionality rules
A dimension may be omitted when:
- it is not relevant to the expression
- it is lawfully inferable during normalization
- it is absent at the foundational layer and introduced later only by lawful projection
A dimension must not be omitted when its absence would make the expression semantically ambiguous in a way that the language cannot legally resolve.
---
# 7. Expression classes
Not all expressions are equally complete.
The language defines three expression classes.
## 7.1 Minimal expression
Contains only the required dimensions.
Example shape:
```txt id="cjwg1z"
{
entity: Action,
structure: control
}
```
A minimal expression is legal if:
- it is well-formed
- the combination is permitted by legality rules
- omitted dimensions may remain omitted or be lawfully inferred later
## 7.2 Qualified expression
Adds one or more optional dimensions that further specify meaning.
Example shape:
```txt id="za1gvt"
{
entity: Action,
structure: control,
interaction: confirm,
evaluation: primary
}
```
## 7.3 Refined expression
A qualified expression after lawful contextual refinement and normalization.
This is the form consumed by downstream projection profiles and the resolution mechanisms that fulfill §14.
---
# 8. Well-formedness rules
These are syntactic-semantic rules of the language.
## 8.1 Rule W-01
Every expression must contain valid terms from approved foundational registries.
## 8.2 Rule W-02
No dimension may appear twice in contradictory form within the same expression.
## 8.3 Rule W-03
A term must belong to the correct dimension.
A `State` term cannot be used where an `Evaluation` term is expected, and so on.
## 8.4 Rule W-04
A structural expression must be explicit enough to be distinguishable from its nearest semantic neighbors.
If an expression remains ambiguous after all lawful inference, it is invalid.
## 8.5 Rule W-05
Context may not appear alone.
Context only exists as refinement on a base expression.
---
# 9. Legality model
Well-formed does not mean legal.
The language requires legality checking.
## 9.1 Lexical legality
Every term must be:
- defined in the FSL Lexicon
- active in the current FSL version
- legal for its dimension
## 9.2 Structural legality
An expression is structurally legal only if the combination of dimensions is permitted.
## 9.3 Context legality
A contextual refinement is legal only if it narrows or specializes meaning without redefining foundational identity.
## 9.4 Projection legality
An expression may be well-formed and foundationally legal, yet still unsupported by a specific downstream projection profile.
That is a projection concern, not a core language concern.
---
# 10. Legality obligations and matrices
Well-formedness (§8) is checked per expression. Legality is checked per **combination** — and the language requires every legality decision to have a declared owner. The foundational layer defines the obligation here; the actual values — which combinations are legal — are the responsibility of each Projection Profile.
## 10.1 The legality obligation
For every pair of **codified** dimensions whose combination can be invalid, a Projection Profile must declare exactly one legality source:
- **Authorial matrix** — an explicit matrix artifact (e.g. Entity × Structure).
- **Runtime resolution** — a named runtime mechanism resolves legality (e.g. a platform layer that only surfaces applicable states). The profile must name the mechanism.
- **Structural impossibility** — the combination cannot be expressed in the profile's surface, and the profile says so.
A Projection Profile is incomplete if any pair of its codified dimensions lacks a declared legality source.
## 10.2 Non-codified dimensions
Legality obligations follow the dimension's disposition (§13.3):
- an **absorbed** dimension's legality must be recoverable from the absorbing mechanism;
- a **deferred** dimension carries no legality obligation until readmission.
## 10.3 Canonical matrices
These matrices are the canonical illustrations of the obligation. Which of them a profile owes depends on which dimensions it codifies — they are examples, not a fixed checklist:
- **Entity × Structure** — which structures are legal for each entity kind (`Overlay × backdrop` may be legal; `Action × backdrop` is generally illegal).
- **Entity × Interaction** — which interaction kinds are legal for each entity kind (`Selection × toggle.tristate` may be legal; `Feedback × entry.text` is illegal).
- **Interaction × State** — which states are legal for each interaction kind (`toggle.tristate` allows `indeterminate`; `navigate.link` may allow `visited`; `command` does not generally allow `checked`).
- **Structure × Layer** — which layer roles are meaningful for which structural roles (`backdrop × blocking` may be legal; `label × blocking` is generally not).
- **Composition × Refinement** — what refinements are legal under each composition role (`dismissAction` may lawfully bias downstream evaluation or consequence handling; no composition role may redefine entity identity).
Profiles have lawfully needed matrices this list does not name — Entity × Evaluation, Entity × Composition, Entity × Consequence — and future profiles may need others. Conformance is measured against the obligation in §10.1, not against this list.
---
# 11. Normalization model
Normalization transforms a valid expression into canonical internal form before projection.
Normalization is part of the language contract.
## 11.1 Purpose of normalization
Normalization exists to:
- fill lawful defaults
- make implicit semantics explicit when permitted
- produce a canonical form for downstream systems
- avoid repeated ad hoc interpretation
## 11.2 Types of normalization
### A. Defaulting
A dimension may receive a default if the default is explicitly governed.
Example:
- `Action + control` may default to `interaction=command`
### B. Inference
A dimension may be inferred if the inference is explicit, deterministic, and governed.
Example:
- `Selection + toggle.tristate` may make `indeterminate` a legal state even if it is not active
### C. Canonicalization
Equivalent structural forms may be normalized to one canonical representation.
## 11.3 Normalization prohibitions
Normalization must not:
- invent new base identity
- bypass legality
- hide ambiguity that should instead be rejected
- smuggle in projection-specific terms into the foundational layer
## 11.4 Concurrent activation
Every dimension in an expression is single-valued (§6.1) — but at runtime an environment may activate several State terms simultaneously (an item can be at once selected, focused, and hovered). A profile that must resolve concurrent activations into a single term must declare a **deterministic, total resolution order**.
A resolution order that collapses Lexicon-distinct terms into one (for example, resolving a selection activation to `checked`) is a **lossy projection decision**. It is held to the same standard §13.3 applies to absorbed dimensions: declared, justified, and either recoverable from the resolving mechanism or carrying an explicit readmission criterion. A profile may not collapse distinct terms silently.
---
# 12. Context refinement model
Context is part of the language, but it is tightly constrained.
## 12.1 What context may do
Context may:
- narrow interpretation
- select among lawful alternatives
- specialize downstream projection
- encode known environmental constraints
## 12.2 What context may not do
Context may not:
- redefine `entity`
- contradict legality matrices
- collapse distinctions between dimensions
- introduce projection-only meaning into the foundational layer
## 12.3 Context classes
The language recognizes the following context classes:
- `composition`
- `environment`
- `interactionEnvironment`
- `mode`
- `density`
- `accessibilityPreference`
- `platformCondition`
Any new context class must be governed as an extension.
---
# 13. Projection interfaces
The Structural Language must support projection, but it must not hard-code the structure of downstream systems.
Projection is handled by **Projection Profiles**.
## 13.1 Required projection targets
The architecture must support at least:
### Component Semantics Projection
Derives:
- semantic identity for the component model
- part/topology semantics
- relational/compositional semantics
- interaction legality for components
### Semantic Token Projection
Derives:
- family-specific semantic forms
- semantic contracts
- semantic addresses
- projection-level legality rules
## 13.2 Projection boundary rule
If a term exists only because a downstream projection needs it, it does not belong in the Structural Language.
## 13.3 Profile dimension dispositions
A Projection Profile is not required to codify every foundational dimension identically. Each dimension in a profile must declare one of three dispositions:
- **Codified** — the profile exposes the dimension with its own registry and legality rules. The canonical case.
- **Absorbed** — the profile declares that the dimension's semantic content is fully captured by another mechanism already present in the profile, and the dimension is therefore not exposed as independent. The profile must name the absorbing mechanism and justify why no meaning is lost.
- **Deferred** — the profile acknowledges the dimension, reserves its name, but does not yet codify it. The profile must state the criterion that will graduate the dimension from deferred to codified.
A disposition is legal only if it preserves foundational meaning. A profile may not **silently** omit a dimension, nor may it absorb a dimension whose distinctions cannot be recovered from the absorbing mechanism.
---
# 14. Resolution contract
The Structural Language does not require a resolution engine. It requires that resolution be lawful — and it defines that requirement as a contract.
The choice of meaning is not deterministic: authors choose terms, context refines them, taste exists. What must be deterministic is the projection of a chosen expression into its result. The contract governs only that projection.
A conforming system must provide the following resolution functions, and must name the owner of each:
- **Validate** — deliver a legality verdict from the declared legality sources (§9, §10)
- **Normalize** — apply lawful defaults, inference, and canonicalization (§11)
- **Resolve** — reduce concurrent activations through a declared, total order (§11.4)
- **Project** — translate the refined expression into a projection profile's form (§13)
- **Explain** — make every verdict and projection derivable from declared sources, not local interpretation
The contract's inputs are: a semantic expression, the active lexical registries, the declared legality sources, the normalization rules, contextual refinement inputs, and a selected projection profile. Its outputs are: the normalized expression, a legality verdict, the projected semantic form, and an explanation.
A single resolver engine that performs every function is one lawful fulfillment of this contract. A pipeline of distributed mechanisms, each owning one function, is another.
What makes token resolution deterministic is that every resolution function has a declared owner — not that one program performs them all.
---
# 15. Conformance requirements
A system conforms to the FSL Structural Language only if it:
1. uses the FSL Lexicon as its foundational vocabulary
2. forms expressions in the canonical shape defined here
3. meets the legality obligations of §10
4. implements normalization explicitly
5. treats context as lawful refinement, not free reinterpretation
6. uses Projection Profiles for all downstream derivation
7. exposes enough information for deterministic explanation
---
# 16. Minimal examples
## 16.1 Action control
```txt id="j3rhhf"
{
entity: Action,
structure: control
}
```
This is a legal minimal expression if `Action × control` is legal.
---
## 16.2 Destructive dismissive overlay flow
```txt id="4rn11t"
{
entity: Overlay,
structure: backdrop,
interaction: status.interruptive,
consequence: destructive,
layer: blocking
}
```
This is valid only if:
- `Overlay × backdrop` is legal
- `status.interruptive` is legal under that entity/structure combination
- `blocking` is legal for `backdrop`
---
## 16.3 Tri-state selection control
```txt id="4l3qcb"
{
entity: Selection,
structure: selectionControl,
interaction: toggle.tristate,
state: indeterminate
}
```
This expression exists specifically to prove that the language can represent semantics that cannot be safely reduced to “selected or not”.
---
# 17. Extension model
The Structural Language supports extensions.
An extension is legal only if it:
- introduces meaning not already expressible
- does not duplicate existing dimensions
- does not contradict foundational meaning
- declares its legality rules
- declares its normalization rules if needed
- declares whether it belongs to the foundational or projection stratum
Extension must be rare.
## 17.1 Projection renaming
A Projection Profile may introduce new names for foundational dimensions when the projection name better models the projection's domain, provided:
1. The mapping from foundational term to projection term is explicit and documented in the projection artifact.
2. The foundational vocabulary is preserved in meaning.
3. The projection name does not introduce new semantic content that belongs in the foundational layer.
Example: a Component Semantics Projection could rename the `Entity` dimension to `Responsibility` — values identical, only the dimension name changes to fit the component model. A profile may equally choose to keep the foundation names; keeping them is the default posture.
---
# 18. Final statement
The FSL Structural Language is the formal structure of the foundational semantic language — it turns the Lexicon into a real language.
Its purpose is not to solve tokens or components directly.
Its purpose is to make it possible for both to derive from the same semantic language, and for resolution to operate deterministically through declared owners rather than local interpretation.
---
## Foundational Semantic Language
# Foundational Semantic Language (FSL)
> **FSL is the semantic foundation from which components, tokens, themes, and tooling are derived.**
UI systems become incoherent when meaning is defined locally — each component invents its own semantics, each token system invents its own vocabulary, and the gaps are filled by conventions that drift over time. FSL solves this by establishing a single source of semantic truth that all downstream systems derive from rather than define independently.
FSL is not styling, not a token tree, not a component API. It is the formal language of meaning that precedes all of those.
## Architecture
FSL is composed of two normative artifacts:
**[FSL Lexicon](./fsl-lexicon.md)** — the controlled vocabulary. Defines the canonical meaning of every core term across nine semantic dimensions: Entity Kind, Structural Role, Interaction Kind, Composition Role, Evaluation, Consequence, State, Layer Role, and Context Class.
**[FSL Structural Language](./fsl-structural-language.md)** — the grammar. Defines how lexicon terms combine into valid semantic expressions, what combinations are legal, how context may refine meaning, and how downstream projections must derive from the foundation.
## What derives from FSL
Every downstream semantic system is a **projection** of FSL — it derives from the foundation and must not define its own incompatible vocabulary. This page is the status ledger for the layers; the two normative artifacts above never carry implementation status.
- **Semantic Token Projection** ([Token Model](/docs/design/design-system/design-tokens/model) and family docs) — maps FSL to token families and addresses. **Implemented** by `@ttoss/fsl-theme`.
- **Component Semantics Projection** ([Component Model](/docs/design/design-system/components/component-model)) — maps FSL to the component model. **Implemented** by `@ttoss/fsl-ui`; the Component Model document names its source-of-truth files.
- **Resolution contract** ([FSL Structural Language §14](./fsl-structural-language.md)) — the obligation that every resolution function has a declared owner. **Satisfied (distributed)** — each function is owned by a shipped mechanism:
| Function | Owner (shipped) |
| :----------------------- | :------------------------------------------------------------------------------------- |
| Typed inputs / parse | TypeScript vocabulary types (`ComponentMeta`, vocabulary tuples in `@ttoss/fsl-ui`) |
| Legality verdict | `ENTITY_*` matrices + contract tests (build-time, `@ttoss/fsl-ui`) |
| Normalization / defaults | Per-component documented defaults + `ENTITY_TOKEN_MAPPING` |
| State resolution | React Aria render props + `STATE_PRIORITY` cascade (runtime) |
| Projection | `resolveInteractiveStyle` (`@ttoss/fsl-ui`) + `toCssVars` (`@ttoss/fsl-theme`) |
| Explanation | `CONTRACT.md` + `llms.txt` (AI-facing artifacts), derivable from the declared matrices |
## The guarantee
The same semantic expression, in the same context, always produces the same result — regardless of which projection consumes it. This is only possible because meaning is defined once at the foundation.
---
## Design System
The ttoss Design System provides a comprehensive foundation for building consistent, accessible, and scalable digital products.
## Core Principles
**1. Easy to use**
Make it simple for newcomers to adopt our system. Easy to use means easy to change and experiment with, enabling rapid iteration.
**2. Simple with minimal dependencies**
Focus on small, focused APIs that cover common use cases while keeping complexity low.
**3. Flexible, not rigid**
Balance standardization with creative freedom. Enable both efficient standard builds and innovative custom solutions.
## Multi-Brand Support
Our system excels at supporting multiple brands through:
- **Theme Switching**: Different brands using the same component library
- **Token Override**: Brand-specific values while maintaining structure
- **Flexible Components**: Adaptable to various visual styles
## Key Benefits
Our design system delivers value aligned with [product development principles](/docs/product/product-development/principles):
- **Single Source of Truth**: Centralized design decisions following [E1: Quantified Overall Economics](https://ttoss.dev/docs/product/product-development/principles#e1-the-principle-of-quantified-overall-economics-select-actions-based-on-quantified-overall-economic-impact)
- **Cross-Team Collaboration**: Shared vocabulary between design and engineering
- **Rapid Prototyping**: Quick testing and iteration enabled by [FF8: Fast-Learning Principle](https://ttoss.dev/docs/product/product-development/principles#ff8-the-fast-learning-principle-use-fast-feedback-to-make-learning-faster-and-more-efficient)
- **Visual Consistency**: Unified experience across products
- **Scalability**: Support for multiple products and brands
## Implementation
For engineering details on how this system is realized in ttoss:
- **[Theme Provider](/docs/design/theme-provider)** — theme setup, switching, and customization
- **[UI Components](/docs/design/ui-components)** — reference component implementations
---
## Document Map
Single navigation table for all foundational design-system documents. Open the file whose question matches your task — do not read in order.
### Foundational Semantic Language (FSL)
| Document | Read when you need… |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| [`fsl/index.md`](./fsl/index.md) | Overview of FSL: what it is, the two normative artifacts, what derives from it. |
| [`fsl/fsl-lexicon.md`](./fsl/fsl-lexicon.md) | Canonical dictionary — the meaning of every core term across the nine semantic dimensions (Entity Kind, Structural Role, etc.). |
| [`fsl/fsl-structural-language.md`](./fsl/fsl-structural-language.md) | Grammar — how lexicon terms combine into valid expressions, legality rules, and how downstream projections must derive from FSL. |
### Design Tokens — architecture & governance
| Document | Read when you need… |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| [`design-tokens/index.md`](./design-tokens/index.md) | Entry point: layered architecture (`core → semantic → component`) and the full family map. |
| [`design-tokens/quick-reference.md`](./design-tokens/quick-reference.md) | Intent → token cheatsheet for quick selection. |
| [`design-tokens/model.md`](./design-tokens/model.md) | Architectural contract: invariants, RawValue exception inventory, FSL → token grammar projection. |
| [`design-tokens/modes.md`](./design-tokens/modes.md) | How modes (light/dark/etc.) remap semantic references without mutating core values. |
| [`design-tokens/theme-authoring.md`](./design-tokens/theme-authoring.md) | How to design and review a theme — owns the Theme Brief and Formal Style Profile formats. |
| [`design-tokens/governance.md`](./design-tokens/governance.md) | Public-contract rules: deprecation, naming, additions, removals. |
| [`design-tokens/validation.md`](./design-tokens/validation.md) | Build-time and runtime validation of the token contract. |
### Token families (foundation)
| Document | Family |
| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| [`design-tokens/families/colors.md`](./design-tokens/families/colors.md) | Colors — UX/role/dimension/state grammar, FSL Entity Kind mapping, role coverage. |
| [`design-tokens/families/typography.md`](./design-tokens/families/typography.md) | Typography — families, weights, ramps, semantic text styles. |
| [`design-tokens/families/spacing.md`](./design-tokens/families/spacing.md) | Spacing — inset/gap/gutter/separation patterns and the responsive engine. |
| [`design-tokens/families/sizing.md`](./design-tokens/families/sizing.md) | Sizing — UI/layout ramps, hit targets, viewport behaviors. |
| [`design-tokens/families/radii.md`](./design-tokens/families/radii.md) | Radii — corner curvature contracts (`control`, `surface`, `round`). |
| [`design-tokens/families/borders.md`](./design-tokens/families/borders.md) | Borders — line widths/styles and semantic line contracts. |
| [`design-tokens/families/elevation.md`](./design-tokens/families/elevation.md) | Elevation — shadow recipes and semantic surface strata. |
| [`design-tokens/families/opacity.md`](./design-tokens/families/opacity.md) | Opacity — semantic transparency contracts. |
| [`design-tokens/families/motion.md`](./design-tokens/families/motion.md) | Motion — durations, easings, semantic motion specs. |
| [`design-tokens/families/z-index.md`](./design-tokens/families/z-index.md) | Z-Index — global stacking layers. |
| [`design-tokens/families/breakpoints.md`](./design-tokens/families/breakpoints.md) | Breakpoints — viewport thresholds (infrastructure-only, no semantic layer). |
### Data Visualization (optional extension)
| Document | Read when you need… |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| [`design-tokens/data-visualization/index.md`](./design-tokens/data-visualization/index.md) | Overview of the dataviz extension — when and how to enable it. |
| [`design-tokens/data-visualization/dataviz-model.md`](./design-tokens/data-visualization/dataviz-model.md) | Architectural extension of the token model for analytical meaning. |
| [`design-tokens/data-visualization/dataviz-colors.md`](./design-tokens/data-visualization/dataviz-colors.md) | Semantic roles for color in analytical contexts. |
| [`design-tokens/data-visualization/dataviz-encodings.md`](./design-tokens/data-visualization/dataviz-encodings.md) | Non-color encoding channels (shape, pattern, position, etc.). |
### Components
| Document | Read when you need… |
| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| [`components/index.md`](./components/index.md) | Overview of the component framework. |
| [`components/component-model.md`](./components/component-model.md) | Component Semantics Projection — how components derive from FSL and consume semantic tokens. |
| [`components/icon-system.md`](./components/icon-system.md) | Icon model and conventions. |
---
## Design
# Design at ttoss
We're open sourcing our design department to share how we approach design and build digital products that scale.
## What You'll Find Here
- **[Design System](/docs/design/design-system)**: Our design system with tokens, components, and guidelines
- **[Getting Started](/docs/design/getting-started)**: Setup and basic usage
## Our Design Philosophy
**Design as Code**: We treat design decisions as code - versioned, documented, and systematically applied across all products.
**Progressive Enhancement**: Start with solid foundations (tokens) and build up to complex components and patterns.
**Accessibility First**: Every design decision considers accessibility from the ground up, not as an afterthought.
## Quick Start
New to our design system? Start with:
1. **[Getting Started Guide](/docs/design/getting-started)** - Set up and basic usage
2. **[Design Tokens](/docs/design/design-system/design-tokens)** - Understanding our design foundation
3. **[Storybook](https://storybook.ttoss.dev)** - Interactive component explorer
---
## Getting Started
The design system ships as two packages: [`@ttoss/fsl-theme`](https://www.npmjs.com/package/@ttoss/fsl-theme) (design tokens, themes, modes) and [`@ttoss/fsl-ui`](https://www.npmjs.com/package/@ttoss/fsl-ui) (semantic React components built on React Aria Components).
```bash
pnpm add @ttoss/fsl-ui @ttoss/fsl-theme react-aria-components
```
Mount the theme once at the root; every component reads CSS-variable tokens from it:
```tsx
const theme = createTheme(); // base theme + dark alternate
export const App = () => {
return (
console.log('pressed')}>
Save
);
};
```
From here:
- **Integrate the theme** (SSR, Next.js, mode switching, custom themes) — [`@ttoss/fsl-theme` README](https://github.com/ttoss/ttoss/blob/main/packages/fsl-theme/README.md)
- **Use the components** (semantic props, customization knobs) — [`@ttoss/fsl-ui` README](https://github.com/ttoss/ttoss/blob/main/packages/fsl-ui/README.md) and the [UI Components overview](/docs/design/ui-components)
- **Pick tokens by intent** — [Design Tokens quick reference](/docs/design/design-system/design-tokens/quick-reference)
- **Understand the model** — [Design System document map](/docs/design/design-system)
---
## Flat2
# Flat 2.0
## Definition
Flat 2.0 is a visual language that preserves the reduction, clarity, and screen-native posture of flat design while reintroducing selected visual cues that improve hierarchy, affordance, and interaction confidence.
Strict Flat minimized 3D cues, textures, gradients, and material simulation in order to emphasize simple forms, typography, spacing, and color. Flat 2.0 keeps that reduced visual logic, but rejects the idea that useful signifiers must be removed in the name of purity. In industry discourse, this evolution is often described as **Flat 2.0**, **almost flat**, or **semi-flat**. The terminology is not fully standardized, but the underlying idea is consistent: preserve the strengths of Flat while restoring restrained depth, tonal variation, and state clarity where strict flatness proved too brittle in real interfaces. ([IxDF - Interaction Design Foundation][1])
Flat 2.0 is therefore not a return to skeuomorphism. It does not restore heavy realism, ornamental texture, or material simulation as a primary language. Instead, it introduces **just enough** layering, shadow, gradient, contrast edge, and state differentiation to make interfaces clearer and more usable without abandoning visual economy. Material’s use of bounded elevation is a strong example of this broader correction, even though Material is a full design system rather than a synonym for Flat 2.0. ([UXPin][2])
In ttoss, Flat 2.0 is a **Visual Language Reference**. It may influence Formal Style Profiles, Theme Archetypes, and Built-in Themes, but it must not redefine semantic meaning, rename semantic tokens, or create appearance-based public vocabulary.
## Historical and Conceptual Context
Flat 2.0 emerged because strict Flat exposed real weaknesses in production UI. Flat design gained force through modernist influences and digital product systems such as Metro, which emphasized a minimalist, type-centric, boldly digital language. But once Flat became widely applied, designers discovered that removing too many signifiers weakened clickability, hierarchy, and perceived clarity. The result was not a rejection of Flat, but an evolution of it. Microsoft’s “authentically digital” framing helps explain the original shift, while later industry discussions around “almost flat” or “Flat 2.0” describe the corrective phase that followed. ([Microsoft Learn][3])
Flat 2.0 is best understood as a **matured operational branch** of Flat rather than a separate historical movement. It keeps the modern digital reduction of Flat, but accepts that real products need bounded depth, stronger states, and more explicit target distinction. This makes Flat 2.0 less of a visual reaction and more of a practical systems adjustment. ([UXPin][2])
## Formal Signature
Flat 2.0 is defined by a distinct combination of traits rather than a single effect.
Typical signals include:
- mostly flat surfaces with restrained depth cues
- subtle shadows or layered separation
- soft gradients or tonal variation used sparingly
- clearer button, link, and control signifiers than strict Flat
- stronger state differentiation for hover, focus, selected, and active states
- continued reliance on typography, spacing, and color for hierarchy
- reduced ornament, but not a total ban on surface distinction
- low-material rather than anti-material posture
In practice, Flat 2.0 usually looks like an interface that is still recognizably flat, but no longer dogmatic about the absence of cues. It accepts that some amount of shadow, contrast edge, layer offset, or motion emphasis may be necessary to make interaction legible. That is why it became the more durable form of Flat in production systems. ([UXPin][2])
## What It Optimizes For
### 1. Reduced visual clutter with better affordance
Flat 2.0 tries to preserve the strengths of Flat — clarity, scalability, speed, and screen-native composition — while reducing one of its biggest weaknesses: weak interaction cues.
### 2. Hierarchy without heavy material simulation
Where strict Flat often depends almost entirely on typography, spacing, and color, Flat 2.0 adds a constrained layer of depth and tonal separation. This makes surface hierarchy easier to read, especially in cards, panels, menus, dialogs, and multi-layered product surfaces.
### 3. Production realism
Flat 2.0 works better in real products because it accepts that interfaces need visible states, clearer target distinction, and bounded layering. It is more compatible with large systems, dense apps, and complex workflows because it tolerates the cues those environments actually need.
### 4. Theming flexibility
Flat 2.0 is more adaptable than strict Flat because it allows a wider range of expression while keeping a fundamentally low-ornament structure. It can support restrained enterprise themes, soft consumer themes, and more premium or expressive directions as long as depth and surface cues remain bounded.
## Risks and Failure Modes
### 1. Becoming an undefined middle
The biggest danger of Flat 2.0 is conceptual looseness. Because it is a corrective family rather than a rigid canon, teams can use “Flat 2.0” to justify almost any mixture of shadows, gradients, cards, and softened surfaces. When this happens, the style stops being a language and becomes a vague middle ground.
### 2. Ornament creeping back without discipline
Flat 2.0 fixes Flat’s worst excesses, but it can easily drift into decorative gradients, unnecessary shadows, or visual polish that adds mood without adding comprehension. Once the corrective cues stop serving hierarchy, signification, or interaction clarity, the interface loses the very discipline that made Flat valuable.
### 3. Hidden inconsistency across states
Flat 2.0 improves clickability and hierarchy only if interactive states are handled systematically. If buttons get shadows but links do not, or cards feel layered but dialogs do not escalate clearly, the language becomes inconsistent. In a system context, Flat 2.0 fails when its cues are selectively decorative rather than structurally disciplined.
### 4. Mistaking Material for Flat 2.0 in full
Material is useful as an example of corrective layering, but Flat 2.0 should not be equated with Material. Material is a full design system with spatial, motion, and component logic of its own. Flat 2.0 is broader and lighter: it borrows the idea of restrained recovery of cues, not the entire system. ([UXPin][2])
## Token Impact Map
Flat 2.0 has a broader and more balanced token impact than strict Flat.
### High impact
- **Colors** — Color remains central, but Flat 2.0 usually uses more tonal nuance, softer separation, and stronger contrast logic for layered surfaces and state distinction.
- **Elevation** — Elevation becomes a bounded but meaningful part of the language. Unlike strict Flat, Flat 2.0 usually needs a clear depth posture, even if it remains subtle.
- **Borders** — Borders continue to matter for control boundaries, selected states, and focus clarity, but they can now work alongside restrained depth instead of carrying the whole burden alone.
- **Spacing** — Layered but restrained surfaces require disciplined spacing to keep hierarchy readable without becoming noisy.
- **Typography** — Typography still carries hierarchy heavily, but Flat 2.0 reduces its burden by allowing limited layer cues back into the system.
### Medium impact
- **Radii** — Curvature matters more in Flat 2.0 because it helps distinguish product posture: restrained, soft, technical, or premium.
- **Motion** — Motion becomes more meaningful than in strict Flat because transitions, entry/exit behavior, and hover/press feedback can reinforce the shallow layer model.
- **Opacity** — Flat 2.0 may use softened panels or restrained translucency, but opacity should remain subordinate to semantic color and depth logic.
### Low impact
- **Z-Index** — Still mostly structural rather than stylistic. Flat 2.0 affects perceived depth more than global layer ordering.
- **Breakpoints** — No direct stylistic ownership; only indirect influence through density and composition strategy.
## Token-Layer Fit vs Recipe-Layer Fit
### Strong token-layer fit
Flat 2.0 maps well to token-level control for:
- restrained but nonzero elevation posture
- line and border restraint
- moderated tonal contrast
- radius posture
- spacing density posture
- fast, meaningful motion defaults
- color mappings that preserve both flat clarity and shallow hierarchy
### Recipe-layer fit
Flat 2.0 still needs recipe-level handling for:
- button recipes and ghost-button discipline
- card surfaces, surface nesting, and container composition
- interactive emphasis rules for menus, drawers, overlays, and panels
- selected/current-state treatments that combine line, color, and shallow depth
- link styling in content-rich contexts
### Mixed fit
Some traits require both token and recipe support:
- surface hierarchy in dense dashboards or enterprise screens
- compositional separation between content surfaces and controls
- interaction confidence in hybrid low-material UIs
- restrained use of gradients, highlights, or translucency so they remain systematic instead of ad hoc
## Formal Style Profile
The operational translation of Flat 2.0 into ttoss terms, in the canonical
[Formal Style Profile](/docs/design/design-system/design-tokens/theme-authoring#formal-style-profile)
format: indexed by token family, using the five constraint levels defined there. Families this reference does not constrain (sizing, z-index, breakpoints) are omitted — the base authoring doctrine applies to them unchanged.
### 1. Colors
**Posture:** disciplined palette with explicit role and state contrast, carrying more tonal nuance than strict Flat.
#### Preferred
- clear neutral foundation, disciplined accent palette, slightly richer tonal steps than strict Flat, explicit role contrast
- strong interactive contrast, explicit state distinction, clear separation between surface layers
#### Tolerated
- mild gradients or tonal transitions that reinforce hierarchy without becoming decorative
#### Discouraged
- broad atmospheric gradients used only as mood
- subtle low-contrast layering that only designers notice
#### Forbidden
- color treatment that blurs interaction, hierarchy, or semantic role boundaries
- relying on tone-only nuance where focus, selected, or current states need stronger differentiation
### 2. Typography
**Posture:** carries hierarchy strongly, but no longer alone — restored layer cues share the load.
#### Preferred
- clean sans-serif, strong hierarchy, less typographic burden than strict Flat
#### Tolerated
- more expressive display use in premium themes
#### Discouraged
- typography overcompensating for weak structural cues
#### Forbidden
- decorative type carrying interaction meaning by itself
### 3. Spacing
**Posture:** disciplined rhythm keeping layered-but-restrained surfaces readable.
#### Preferred
- balanced density
#### Tolerated
- compact density if hierarchy cues remain strong
#### Discouraged
- dense surfaces with shallow cues and weak spacing
#### Forbidden
- compressed layouts where shallow layering cannot be read quickly
### 4. Radii
**Posture:** curvature as a product-posture signal, not ornament.
#### Preferred
- restrained to moderate
#### Tolerated
- softer curvature in consumer or brand-forward themes
#### Discouraged
- overly angular systems if depth cues are also weak
#### Forbidden
- ornamental radius variation without structural purpose
### 5. Borders
**Posture:** structural line work complementing restrained depth instead of replacing it.
#### Preferred
- restrained, structural, complementary to depth rather than replacing it entirely
#### Tolerated
- stronger outlines in technical or dense products
#### Discouraged
- border removal where depth remains too weak to replace it
#### Forbidden
- collapsing surface and control boundaries into a single indistinct plane
### 6. Elevation
**Posture:** shallow and bounded — depth returns as a real cue, but a disciplined one.
#### Preferred
- shallow and bounded
#### Tolerated
- moderate surface lift for overlays, cards, and modals
#### Discouraged
- ornamental depth or many competing elevations
#### Forbidden
- realism-heavy or unlimited shadow systems
### 7. Motion
**Posture:** reinforces the shallow spatial model; never performs on its own.
#### Preferred
- restrained but meaningful
#### Tolerated
- motion that reinforces shallow spatial logic and state transitions
#### Discouraged
- decorative motion detached from hierarchy or state
#### Forbidden
- theatrical motion that conflicts with low-material visual language
### Cross-family rules
**Material posture.** The defining constraint of Flat 2.0, spanning elevation, colors, and opacity: the language stays low-material and shallow-layered.
- **Tolerated:** restrained translucency or surface softness
- **Discouraged:** literalized material simulation
- **Forbidden:** full skeuomorphic texture, gloss, or tactile illusion as a dominant language
## Archetype Affinity
### Primary fit
- **Enterprise Neutral** — Flat 2.0 is stronger than strict Flat here because it improves hierarchy and interaction clarity without losing restraint.
- **Technical Precision** — Flat 2.0 works well when shallow depth is carefully bounded and paired with explicit lines, spacing, and focus treatment.
- **Soft Product** — Flat 2.0 is often a better base than strict Flat because it supports friendliness and clarity without requiring a heavy material system.
### Partial fit
- **Editorial Minimal** — Flat 2.0 can support editorial systems, but many editorial interfaces prefer less surface structure and more typographic emphasis than Flat 2.0 typically uses.
- **Expressive Premium** — Flat 2.0 can contribute, especially through shallow layering and controlled gradients, but premium expression often pushes beyond its restrained posture.
## Implementation Notes
Flat 2.0 should be implemented as **disciplined recovery of cues**, not as permission to decorate.
In ttoss terms, that means:
- use semantic colors for role clarity first
- use limited elevation to distinguish surfaces
- preserve strong border, focus, current, and selected contracts
- keep motion meaningful and short
- prefer a small number of stable depth levels rather than many ad hoc shadows
- treat gradients, translucency, or glows as rare systemized tools, not as general embellishment
The practical test is simple: if removing the extra cues would make the interface ambiguous, those cues are doing useful work and should be formalized. If removing them changes only the mood, they are probably ornamental and should be constrained or removed.
Flat 2.0 works best when its corrective elements are:
- small in number
- consistent in behavior
- tied to hierarchy or interaction
- validated as part of the system rather than sprinkled case by case
## Summary
Flat 2.0 is the mature operational branch of Flat.
It preserves the reduction, clarity, and screen-native posture that made Flat influential, but rejects Flat’s most dogmatic failure mode: removing so many cues that hierarchy and clickability become fragile. It is best understood not as a weak compromise, but as a **systems correction**: a restrained reintroduction of depth, state, and distinction where real interfaces need them. ([UXPin][2])
For ttoss, Flat 2.0 is one of the most useful production-facing visual references. It maps cleanly onto token families, supports strong theme archetypes, and remains highly compatible with a semantic-contract-first architecture — as long as it is kept bounded, structural, and anti-ornamental.
---
[1]: https://www.interaction-design.org/literature/topics/flat-design 'What is Flat Design? | IxDF'
[2]: https://www.uxpin.com/studio/blog/the-evolution-of-the-flat-design-revolution/ 'The Evolution of the Flat Design Revolution | UXPin'
[3]: https://learn.microsoft.com/en-us/shows/teched-australia-2012/dev213 'How I Became Authentically Digital - An Introduction to the Windows 8 UI Design Language | Microsoft Learn'
---
## Style References
Style references document **visual languages**, not semantic meaning.
Their purpose is to give ttoss a disciplined way to study recurring interface styles, understand what formally defines them, identify the tradeoffs they introduce, and translate them into theme constraints **without breaking the semantic contract of the design system**. Material describes styles as the visual aspects that give a UI a distinct look and feel, while Carbon treats themes as collections of visual attributes applied to stable token roles. That distinction is central here: visual language may vary, but semantic roles must remain stable. ([m3.material.io](https://m3.material.io/styles))
In ttoss, semantic tokens remain the public API of meaning-bearing families. Themes may change core values and semantic mappings, but they must not change semantic meaning or create a parallel vocabulary. Style references therefore sit **below** the semantic contract and **above** concrete theme implementations: they inform visual direction, but they do not redefine meaning.
## Position in the architecture
Style references are part of the **Visual Reference Architecture**.
That architecture separates concerns that are often conflated:
- **Semantic Contract** — stable meaning, naming, governance, validation
- **Visual Language Reference** — technical reference for a recurring visual language
- **Formal Style Profile** — operational style constraints derived from a reference, published in the canonical format defined by [Theme Authoring](/docs/design/design-system/design-tokens/theme-authoring#formal-style-profile)
- **Theme Archetype** — product-facing visual posture
- **Built-in Theme** — concrete token implementation
- **Interaction Posture** — attentional and behavioral stance
- **AI Context Pack** — machine-oriented structured context for theme generation and implementation
This separation is necessary because style is not a single artifact. In practice, design systems, platform guidelines, and generative tools use “style” to mean different things: formal construction rules, theming systems, materials, or probabilistic visual steering. ttoss keeps these layers distinct so that appearance can evolve without semantic drift.
## What a style reference is
A style reference is a **technical document for a recurring visual language**.
It describes a style in terms of:
- conceptual and historical context
- formal visual signature
- what it tends to optimize for
- risks and failure modes
- impact on token families
- token-layer fit versus recipe-layer fit
- likely influence on theme archetypes
A style reference is not a moodboard, not a gallery of examples, and not a built-in theme. It is a structured reference artifact that makes a visual language easier to reason about, easier to implement selectively, and harder to misuse.
## What a style reference is not
A style reference is **not** the semantic contract. Meaning remains defined by the token model.
A style reference is **not** a theme archetype. Archetypes are product-oriented theme postures such as enterprise, editorial, technical, or expressive.
A style reference is **not** a built-in theme. Built-in themes are concrete implementations of tokens, mappings, modes, and optional recipes.
A style reference is **not** a component recipe library. Some styles require materials, rendering behavior, component composition, or interaction rules that cannot be expressed through tokens alone. Apple’s HIG and current materials guidance are good examples of this: material behavior is a system-level visual effect, not just a color or shadow choice. ([developer.apple.com](https://developer.apple.com/design/human-interface-guidelines/))
A style reference is **not** an interaction philosophy. Interaction posture governs guidance, interruption, escalation, and steerability. That is a different layer from visual language.
## Why this library exists
This library exists for four reasons.
First, it creates a **shared technical vocabulary** for discussing styles without reducing them to vague aesthetic labels.
Second, it makes visual languages **comparable**. A good style reference helps clarify what a style really is, what it borrows from, and where it breaks down.
Third, it makes style **operationalizable**. A style becomes useful to a design system only when it can influence bounded decisions across token families such as color, depth, borders, curvature, spacing, typography, opacity, and motion. IBM’s design language is a strong precedent here: its iconography is not defined by taste alone, but by grid, stroke consistency, proportion, corners, and perspective rules. ([ibm.com](https://www.ibm.com/design/language/iconography/ui-icons/design/))
Fourth, it makes style more useful for **AI-assisted theme creation**. AI systems perform better when the system provides explicit boundaries, known failure modes, and structured distinctions instead of aesthetic prompts alone. That is consistent with ttoss’s broader emphasis on semantic contracts and closed-loop, structurally constrained systems.
## Inclusion criteria
A style is worth documenting only when it is more than a loose aesthetic label.
In this library, a style reference should be:
- historically or culturally recognizable
- formally identifiable across multiple visual dimensions
- useful as a source of constraints for themes
- capable of being discussed in terms of tradeoffs, not only preference
- bounded enough to avoid becoming a catch-all category
Some references are included because they are strong foundations. Others are included because they are cautionary, comparative, or useful sources of selective borrowing. Recommendation level is therefore not the same as relevance.
## Relationship to tokens
Style references do not create a second semantic layer.
They must not introduce public token names such as `flat.button`, `glass.surface`, or `brutalist.border`. Appearance must not replace meaning. Semantic token names continue to express role, context, dimension, state, or analytical function — never visual trend names.
Instead, a style reference may influence:
- core value selection
- semantic mapping posture
- allowed visual ranges per family
- mode tuning
- component or pattern recipes when token control is insufficient
This keeps the system themeable and expressive without compromising semantic stability. Carbon’s theme model is an important precedent: tokens remain universal, roles remain stable, and only values vary to produce a different aesthetic. ([carbondesignsystem.com](https://carbondesignsystem.com/elements/themes/overview/))
## Relationship to archetypes and themes
Style references inform **Theme Archetypes**, and archetypes inform **Built-in Themes**.
The relationship is not one-to-one.
A theme archetype such as `enterprise-neutral` may be influenced by flat or minimalist references. An archetype such as `expressive-premium` may selectively draw from material or glass references. A theme should therefore be understood as a product-facing implementation shaped by one or more references, not as a literal export of one historical style.
## What each reference document must do
Each style reference in this directory is expected to:
1. define the style clearly
2. explain its historical and conceptual context
3. identify its formal signature
4. describe what it tends to optimize for
5. document its risks and failure modes
6. map its impact across ttoss token families
7. distinguish token-layer fit from recipe-layer fit
8. propose an initial formal style profile, indexed by token family and using the five constraint levels, exactly as [Theme Authoring](/docs/design/design-system/design-tokens/theme-authoring#formal-style-profile) defines them — a reference does not invent its own format or level vocabulary
9. identify likely archetype affinity
A style reference that only describes visual taste is incomplete. A style reference becomes useful only when it makes the style technically legible.
## Current references
- [Skeuomorphic](./skeuomorphic.md)
- [Flat 2.0](./flat2.md)
Further references (minimalist, material, glass, neobrutalism, neumorphism, 90s) are planned and will be added as they are authored against the inclusion criteria above. References are not expected to be symmetrical in recommendation level: some are strong sources for production archetypes, others clarify limits, tradeoffs, or cautionary boundaries.
## Principle
This library exists to make visual style **explicit, bounded, and translatable**.
The goal is not to turn ttoss into a catalog of skins.
The goal is to build a disciplined reference layer that helps themes evolve visually while the semantic contract remains stable.
A good style reference should make a visual language easier to understand, easier to borrow from selectively, and harder to misuse.
---
---
## Skeuomorphic
## Definition
Skeuomorphic is a visual language in which digital interface objects mimic real-world objects in appearance, interaction logic, or both, in order to make unfamiliar digital behavior more immediately understandable through familiar physical references. In interaction-design literature, the core idea is not merely ornament, but the use of recognizable real-world cues to make action possibilities easier to infer. Classic examples include trash-can icons, bookshelf metaphors, notepad-like writing surfaces, glossy push-button treatments, and watch faces that resemble analog watches.
Skeuomorphic should not be reduced to “leather textures and fake wood.” That caricature captures only one historical phase of the style. More fundamentally, skeuomorphism is about **transferring familiarity from the physical world into the digital one**. That transfer may happen through surface treatment, object form, motion, control shape, or interaction metaphor. For ttoss, Skeuomorphic is a **Visual Language Reference**: it can influence themes and recipes, but it must not redefine semantic meaning or create appearance-based semantic token names.
## Historical and Conceptual Context
Skeuomorphism became especially prominent during the rise of graphical interfaces and early mobile computing because users were still learning unfamiliar interaction models. Mapping digital behaviors onto familiar physical artifacts reduced the learning burden: files went into folders, deleted items went into a trash can, notes looked like paper, and buttons looked pressable. Interaction Design Foundation explicitly ties skeuomorphism to this role of familiarity and links it to Gibson’s notion of affordances — action possibilities that can be inferred from an object’s form.
Historically, early iOS is one of the clearest examples of a strongly skeuomorphic mobile interface. The style was widely associated with early touch-interface adoption because it translated novel behaviors into recognizable visual and interaction cues for users who had never used touch-based smartphones before. Over time, however, major platforms moved away from literal skeuomorphism as digital conventions became more familiar in their own right. Current Apple HIG guidance emphasizes hierarchy, harmony, and consistency rather than literal physical imitation, which is a useful marker of how platform maturity changes the need for skeuomorphic cues.
Conceptually, skeuomorphism should be understood less as a binary opposite of Flat and more as one strategy for solving a problem of **familiarity, signification, and action inference**. Research in the International Journal of Human-Computer Studies argues that the usual flat-versus-skeuomorphic dichotomy is often muddled because dimensionality and visual metaphor are not the same variable. That work found that flat and skeuomorphic designs are not inherently different at the perceptuomotor level, and that visuo-perceptual familiarity may matter more than dimensionality alone. This is a crucial correction: skeuomorphism is not simply “more 3D.” It is a specific way of using familiarity and metaphor.
## Formal Signature
Skeuomorphic interfaces usually combine several of the following traits:
- visual resemblance to real-world tools, surfaces, or materials;
- explicit object metaphors;
- dimensional or tactile cues such as highlights, shadows, gloss, beveling, or texture;
- control shapes that imply physical manipulation;
- motion or transitions that simulate physical behavior;
- strong emphasis on perceived affordances and familiarity;
- surface treatments that suggest substance, weight, or tactility.
What makes a skeuomorphic interface recognizable is not just realism, but **reference fidelity**: the degree to which the interface intentionally borrows the visual or behavioral logic of a physical counterpart. A skeuomorphic calculator is not just “raised buttons”; it is an interface whose spatial grouping, button topology, and pressability cues all borrow from familiar physical calculators. The same logic applies to analog watch faces, paper notebooks, bookshelf metaphors, or music-production interfaces that mimic physical racks and knobs.
## What It Optimizes For
### 1. Familiarity
The strongest benefit of skeuomorphism is familiarity transfer. By borrowing cues from already-known objects and behaviors, the interface lowers the interpretive burden for new or less digitally fluent users. IxDF explicitly frames this as one of its key functions, and recent empirical work reinforces that familiarity-based design can still improve usability for some populations.
### 2. Perceived affordance
Skeuomorphic interfaces often make possible actions easier to infer. This does not mean they are always objectively better, but they frequently strengthen perceived manipulability, especially when users are unfamiliar with the digital environment. The 2020 IJHCS paper is especially useful here: it argues that conventional metaphor can function as a signifier that improves a user’s ability to perceive how they can interact with interfaces.
### 3. Transitional onboarding
Skeuomorphism is especially valuable during technology transitions, where users are learning a new medium or moving from a long-familiar physical workflow to a digital one. The 2024 kiosk study for older adults is a strong example: participants over 65 perceived the skeuomorphic version as easier to use, completed tasks more quickly, and performed best when skeuomorphic representation was paired with a linear navigation structure.
### 4. Emotional and tactile richness
Skeuomorphic systems can create warmth, tactility, nostalgia, craft, or premium atmosphere more readily than flatter languages. This is not only a branding point; it can also support trust and comfort in domains where the user benefits from strong sensory familiarity. That said, this advantage is contextual rather than universal.
## Risks and Failure Modes
### 1. Decorative excess
The classic critique of skeuomorphism is that it often accumulates details that no longer serve interpretation. Once the user understands the interaction model, heavy textures, faux materials, and literal simulation can become visual noise. IxDF explicitly notes this shift: what once helped users cross the learning curve can later hold systems back by adding clutter the digital medium no longer needs.
### 2. Obsolete metaphor
Skeuomorphism depends on reference recognition. When the referenced object becomes culturally distant or obsolete, the metaphor weakens. IxDF points to the floppy-disk “Save” icon as a case where the original real-world correspondence has decayed. This is one of the deepest structural risks of the style: its meaning may erode as culture changes.
### 3. Literalism that constrains digital strengths
A digital system is not a physical object. When skeuomorphism is applied too literally, it can preserve unnecessary constraints from the physical world and make the interface less efficient than it could be. This is one reason later digital design movements pushed toward flatter, more native-to-screen approaches. The critique is not that familiarity is bad, but that **excessive fidelity to physical metaphor can suppress the strengths of digital systems**.
### 4. Misdiagnosis of what users actually need
The 2020 IJHCS paper is important because it argues that many debates incorrectly bundle together dimensionality, metaphor, and affordance. In other words, a team may think it needs “more skeuomorphism” when what it really needs is stronger signifiers, better physical compatibility with manipulation, or more familiar visual forms. Skeuomorphism is therefore easy to overprescribe when the real issue is action legibility.
### 5. Poor scalability as a system default
As a broad foundation for modern multi-surface product systems, full skeuomorphism is usually too heavy. It tends to demand recipe-level material simulation, more bespoke component work, more image/asset dependence, and stronger coupling between form and metaphor. This makes it less suitable as a universal base style and more appropriate as a targeted reference for selective borrowing. This is an inference from its dependence on metaphor fidelity, material treatment, and special-case recipes rather than a single broad token posture.
## Token Impact Map
Skeuomorphic has **high impact** on some ttoss families and often exceeds what tokens alone should control.
### High impact
- **Colors** — surface color is often tied to material simulation, warmth, realism, or analog references rather than purely abstract role contrast.
- **Elevation** — skeuomorphic interfaces usually depend on clear dimensional cues, not merely flat separation. Shadow, lift, and perceived substance matter substantially.
- **Borders** — lines often serve as part of tactile or object-like boundaries, not just abstract structural division.
- **Radii** — curvature often correlates with physical-object analogy, containment, and touchability.
- **Motion** — transitions may reinforce physicality, object continuity, or analog behaviors.
### Medium impact
- **Typography** — typography usually becomes secondary to object metaphor and material treatment, but still plays an important role in realism and legibility.
- **Spacing** — spacing often follows metaphor-driven grouping rather than purely abstract rhythm.
- **Opacity** — translucency, veils, and layered material simulation may appear, but opacity is usually subordinate to broader material treatment.
### Low impact
- **Z-Index** — still mostly structural rather than stylistic. Skeuomorphic depth is more about perceived substance than stacking order.
- **Breakpoints** — no direct ownership; any influence is indirect through metaphor preservation across layouts.
## Token-Layer Fit vs Recipe-Layer Fit
### Strong token-layer fit
Skeuomorphic can influence tokens at the level of:
- depth posture;
- line/border presence;
- curvature posture;
- restrained or expressive motion defaults;
- warmer or more material-coded palette direction.
### Recipe-layer fit
Skeuomorphic depends heavily on recipe-level implementation for:
- material simulation;
- tactile surface treatments;
- object-specific control geometry;
- analog spatial grouping;
- transitions that mimic physical behavior;
- metaphor-specific iconography or component composition.
This is the core reason it is not a strong universal foundation style. Much of what makes it recognizably skeuomorphic lives above the token layer.
### Mixed fit
Some traits require both token and recipe support:
- object-like buttons and controls;
- analog-style panels;
- notebook, shelf, dial, or dashboard metaphors;
- hybrid modern interfaces that want familiarity cues without full literal simulation.
## Formal Style Profile
The operational translation of Skeuomorphic into ttoss terms, in the canonical
[Formal Style Profile](/docs/design/design-system/design-tokens/theme-authoring#formal-style-profile)
format: indexed by token family, using the five constraint levels defined there. Families this reference does not constrain (sizing, z-index, breakpoints) are omitted — the base authoring doctrine applies to them unchanged.
### 1. Colors
**Posture:** material-coded and reference-aware, with contrast strong enough that tactility never costs readability.
#### Preferred
- warmer, more material-coded, reference-aware palettes when the metaphor requires them
- clear contrast where tactile cues support action recognition
#### Tolerated
- neutral systems with selective metaphor-supporting accents
- richer tonal range than flat systems
#### Discouraged
- purely abstract palette logic if the interface is trying to preserve strong physical analogy
- low-contrast realism that prioritizes atmosphere over usability
#### Forbidden
- arbitrary material coloration disconnected from metaphor or role clarity
- realism that weakens readability or state distinction
### 2. Typography
**Posture:** supportive of the metaphor, never competing with it.
#### Preferred
- supportive rather than dominant; typography should reinforce the metaphor without becoming decorative clutter
#### Discouraged
- typography that competes with the object metaphor
#### Forbidden
- decorative type that harms legibility or makes the interface feel theatrical rather than usable
### 3. Spacing
**Posture:** moderate density, leaving the metaphor room to be read.
#### Preferred
- moderate, with room for metaphor readability
#### Tolerated
- denser specialized control surfaces when the audience is already familiar with the physical analogue
#### Discouraged
- dense skeuomorphic UIs for general audiences without strong reason
#### Forbidden
- high-density literalism that turns the interface into a noisy replica
### 4. Radii
**Posture:** curvature answers to object logic, not to taste.
#### Preferred
- metaphor-dependent and purposeful
#### Tolerated
- stronger curvature when it supports familiar object logic
#### Discouraged
- expressive curvature unrelated to object metaphor
#### Forbidden
- ornamental corner variation without functional or referential meaning
### 5. Borders
**Posture:** tactile, object-supporting line work that still reads as structure.
#### Preferred
- tactile or object-supporting, structurally meaningful
#### Tolerated
- more detailed boundary language than flatter systems
#### Discouraged
- excessive ornament in every edge and stroke
#### Forbidden
- line treatment that simulates craft while obscuring interaction intent
### 6. Elevation
**Posture:** depth is explicit and carries meaning — it stands for substance, not decoration.
#### Preferred
- explicit and meaningful, tied to perceived substance or interaction
#### Tolerated
- stronger depth than Flat or Flat 2.0
#### Discouraged
- decorative dimensionality without semantic purpose
#### Forbidden
- uncontrolled multi-layer visual noise
### 7. Motion
**Posture:** reinforces object continuity and familiar manipulation.
#### Preferred
- motion that reinforces object continuity or familiar manipulation
#### Tolerated
- richer transitions than flat systems
#### Discouraged
- cinematic motion added only for spectacle
#### Forbidden
- physical simulation that slows down primary workflows
### Cross-family rules
**Material posture.** The defining constraint of the reference, spanning elevation, colors, borders, and opacity: realism is earned by comprehension, never assumed.
- **Preferred:** explicit when the metaphor truly serves comprehension or comfort
- **Tolerated:** partial or selective realism
- **Discouraged:** total realism as a default system language
- **Forbidden:** heavy faux-material treatment when no learning or signification benefit exists
## Archetype Affinity
### Primary fit
- **Soft Product** — when the product benefits from warmth, tactility, or familiarity cues.
- **Specialized Legacy Familiarity** — this is the clearest fit, especially where users are transitioning from physical workflows or long-established metaphors.
### Partial fit
- **Expressive Premium** — selective skeuomorphic borrowing can add tactility or emotional richness, but full literalism is usually too heavy.
- **Technical Precision** — only in specific domains where replicating known physical controls improves comprehension.
### Usually not primary
- **Enterprise Neutral** — skeuomorphic literalism is usually too heavy, too specific, and too recipe-dependent.
- **Editorial Minimal** — the visual and material logic are usually in tension.
## Implementation Notes
Skeuomorphic should be used **surgically**, not universally.
The strongest modern use cases are:
- transition from physical to digital workflows;
- older or less digitally fluent audiences;
- specialized tools whose physical controls are deeply familiar;
- selective emotional/tactile enrichment where the metaphor improves comprehension or comfort.
The weakest use case is full-system literalism applied by default to a modern general-purpose product. In most products, the better question is not “should this theme be skeuomorphic?” but “which familiarity cues, metaphors, or tactile signals are worth borrowing here?” That framing is more consistent with the evidence: visuo-perceptual familiarity and good signifiers matter, but full literal realism is neither always necessary nor always beneficial.
In ttoss terms, Skeuomorphic is best treated as:
- a strong **reference**,
- a weak **universal foundation**,
- and a potentially powerful **selective influence** on themes, recipes, or onboarding-critical flows.
## Summary
Skeuomorphic is the visual language of **familiarity by reference**.
Its value is real: it can reduce learning burden, strengthen perceived affordance, and improve usability in contexts where users benefit from recognizably physical cues. Recent research even shows measurable gains for older adults in kiosk tasks when skeuomorphic design is combined with familiarity-supporting interaction structure.
Its limits are equally real: it can become cluttered, culturally obsolete, over-literal, and too dependent on recipe-level realism to function as a strong universal design-system base. The real lesson is not “skeuomorphism good” or “skeuomorphism bad.” The lesson is that **familiarity, signification, and metaphor should be used deliberately, with proportion, and only where they add real interpretive value.**
---
## ttoss Theme Provider
The Theme Provider is the React integration layer for [`@ttoss/fsl-theme`](/docs/design/design-system/design-tokens/model). It manages theme switching, mode resolution (light / dark / system), SSR flash prevention, and exposes semantic tokens to your component tree.
For setup and usage — `ThemeProvider`, `ThemeScript`, `ThemeHead`, `ThemeStyles`, `useColorMode`, `useTokens`, `useResolvedTokens`, and the Next.js / SSR patterns — see the package [README](https://github.com/ttoss/ttoss/blob/main/packages/fsl-theme/README.md).
---
## Composition guidelines
The [Entity contract](/docs/design/design-system/components/component-model) 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.
They are expressed through the [presentational primitives](/docs/design/ui-components) (`Surface`, `Heading`, `Text`, `Stack`) and the control catalog. Nothing here reaches for a raw `font-size`, `gap`, or shadow — the whole point is that quality comes from the system, so it survives a theme change.
## Depth: layer surfaces, don't flatten them
Every region that is conceptually a distinct object — a card, a panel, a sheet, a dialog body — is a `Surface`, not a bordered `div`. Pick the `level` by how the surface sits relative to the page, never by how it should look:
- `flat` — flush with the page (a section that organizes without lifting).
- `raised` — the default card/panel: sits above the page.
- `overlay` — floats above raised content (menus, popovers).
- `blocking` — the strongest in-flow depth (dialogs).
Depth reads in both modes because `Surface` pairs the elevation shadow with the tonal surface colour at that stratum. In light, shadow carries the lift; in dark, the surface _lightens_ as it rises (a near-black canvas swallows shadows). Do not try to reproduce this by hand — a raised card built from a border alone is the single most common way a dark UI reads as flat and cheap.
Nesting is legal and encouraged: a `raised` card may hold a `flat` sub-region. Keep the ladder shallow — two or three live levels on a screen is plenty.
## Hierarchy: one clear entry point per surface
A surface with no typographic hierarchy gives the eye nowhere to land. Lead each meaningful surface with a `Heading`, and let supporting copy recede:
```tsx
Account settings
Manage how your workspace behaves.
{/* controls */}
```
Choose `Heading level` for document structure (screen-reader order), not for size; reach for `size` only when the visual step must differ from the rank. `tone="muted"` is the sanctioned lever for secondary copy — captions, hints, metadata (`tone` is `Text`'s name for the `muted` Evaluation — a projection rename per FSL §17.1, scoped to text parts). Building hierarchy _is_ choosing which text recedes.
## Rhythm: space from the scale, generously
Lay everything out with `Stack`, never a hand-rolled flex `div`. `direction="vertical"` reads the `gap.stack` scale; `direction="horizontal"` reads `gap.inline`. Group related things tightly and separate unrelated groups loosely — a title and its caption sit at `gap="xs"`, whole sections at `gap="lg"`. Consistent rhythm is more legible than dense packing; when in doubt, give a surface more room, not less.
## Action: exactly one primary per surface
The fastest way to make a screen look amateur is a row of equally-weighted solid buttons. A surface should present **one** primary action; everything else is `muted` or `secondary`:
```tsx
// ✅ one clear primary, the rest recede
Cancel
Save
// ❌ four solid CTAs competing — no hierarchy of action
Save
Publish
Duplicate
Delete
```
A destructive action belongs behind a `ConfirmationDialog`, not sitting armed next to the primary. If a surface seems to need several primaries, it is probably several surfaces.
## Colour: let neutrals carry the structure
The brand accent is a spotlight, not a wash. Structure — surfaces, borders, most text — is carried by the neutral ramp; the accent marks the one thing that matters most on the surface (the primary action, the active tab, a selected item). A screen where everything is branded has nothing emphasized. Feedback colours (`positive` / `caution` / `negative`) express state, never decoration.
## Motion and focus come for free
Do not hand-animate. Transitions and the focus ring are already tokenised and honour `prefers-reduced-motion`; controls carry them. Adding bespoke motion or a custom focus outline breaks the one consistent behaviour a user relies on.
## The shape of a good surface
```mermaid
flowchart TB
S["Surface (raised, padding lg)"] --> ST["Stack (gap lg)"]
ST --> H["Stack (gap xs): Heading + muted Text"]
ST --> C["content — controls in Stacks"]
ST --> A["Stack (horizontal, justify end):muted actions + one primary"]
```
Read it top to bottom: a depth-bearing container, a rhythmic stack, a titled header, content, and a single primary action anchored at the end. Every decision is a named token or primitive — which is exactly why the result stays coherent when the theme changes underneath it.
---
## ttoss UI Components
`@ttoss/fsl-ui` is the React implementation of the [FSL component model](/docs/design/design-system/components/component-model): a component library built on [React Aria Components](https://react-spectrum.adobe.com/react-aria/) where every component declares a formal semantic identity — its Entity — and that identity determines which [`@ttoss/fsl-theme` tokens](/docs/design/design-system/design-tokens/model) 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.
## Catalog
| Entity | Components |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Action | `Button` (command silhouette), `ActionButton` (utility silhouette), `ToggleButton`, `FileTrigger`, `MenuItem` (inside `Menu`), `FormSubmit`, `ActionMenu` (overflow trigger), `ContextualHelp` (the ⓘ beside a field's label) |
| Navigation | `Link`, `Breadcrumbs` / `Breadcrumb`, `Tabs` / `TabList` / `Tab` |
| Disclosure | `Accordion` (`AccordionItem` / `AccordionTrigger` / `AccordionPanel`), `Disclosure` (`DisclosureTrigger` / `DisclosurePanel`) |
| Selection | `Checkbox`, `CheckboxGroup`, `RadioGroup` / `Radio`, `Switch`, `Select` / `SelectItem`, `ToggleButtonGroup`, `TagGroup` / `Tag` |
| Collection | `ListBox` / `ListBoxItem`, `GridList` / `GridListItem`, `Table` (`TableHeader` / `TableColumn` / `TableBody` / `TableRow` / `TableCell`) — the container is Collection, selectable items (`ListBoxItem`, `GridListItem`, `TableRow`) are Selection (ADR-007) |
| Input | `TextField`, `TextArea`, `SearchField` (each with `*Label` / `*Control` / …), `NumberField`, `Slider`, `FieldGroup` (one label over several controls), `ComboBox` / `ComboBoxItem` (typeahead-filtered list — a freeform channel makes a picker Input, ADR-012; items are Selection, ADR-007) |
| Overlay | `Dialog` family (`DialogModal` / `DialogHeading` / `DialogBody` / `DialogActions`), `Menu`, `ConfirmationDialog`, `Popover`, `Tooltip`, `Drawer` |
| Feedback | `ProgressBar`, `Meter`, `StatusLight`, `Toast` / `ToastRegion` |
| Structure | **Presentational primitives** — `Surface` (depth container), `Heading` / `Text` (type scale), `Stack` (layout rhythm), `Box`, `Grid`, `Container`, `AppShell`, `List` / `ListItem`, `Icon`, `Badge`, `Code` — plus `Form` / `FormActions`, `Wizard` (`WizardStep` / `WizardSummary` / `WizardNavigation`), `Separator`, `Group`, `ButtonGroup`, `Toolbar`, `TabPanel` (the content the tabs reveal) |
Waves 1 and 2 of the full React Aria atomic catalog are complete, and Wave 3 has landed `Table` and `ComboBox`; `Tree` and the date/time suite are deferred until an app asks for them. Every component lands with contract tests, keyboard tests, and an axe accessibility suite.
## Customization model
Components have no `style`, `className`, or `size` props. Colors, spacing, and typography come from the theme; a different density is a different semantic component. Geometry the host legitimately owns (dialog width, menu popover sizing) is exposed as `--fsl-*` CSS custom properties with built-in fallbacks:
```css
[data-scope='dialog'] {
--fsl-dialog-max-width: 720px;
}
```
Every element renders `data-scope` / `data-part` (plus `data-evaluation`, `data-consequence`, `data-composition` where the dimension applies) — the stable public surface for CSS targeting and tests.
## Where to go next
- [Composition guidelines](/docs/design/ui-components/composition) — how to compose the primitives and controls so "semantically correct" also reads as "well designed".
- [Component model](/docs/design/design-system/components/component-model) — the theory this package implements, including the Entity → token projection.
- [Design tokens](/docs/design/design-system/design-tokens/model) — the `@ttoss/fsl-theme` grammar the components consume.
- The package's `README.md` (quickstart) and `CONTRIBUTING.md` (authoring rules, ADRs) in `packages/fsl-ui/`.
---
## Engineering
# Engineering at ttoss
Engineering at ttoss is being rebuilt around agents. Not as a tooling upgrade, but as a change in what engineers spend the day doing and what the delivery system has to guarantee on their behalf.
The premise is simple and uncomfortable: when generating code becomes cheap, code stops being the constraint. What stays scarce is knowing what to build, proving that what was built is correct, and being able to undo it when it is not. Every page in this section exists to make one of those three cheap enough to do at the speed agents now produce change.
This section is written to be portable. The examples are ours — our lint budgets, our pipelines, our coverage gates — but the pillars are meant to be lifted into any team's codebase. If you are here to build agentic engineering on your own team, the examples are illustrations, not requirements.
## How to Read This Section
[Why Software Engineering Is Changing](/docs/engineering/why-engineering-is-changing) makes the case that the shift is structural rather than fashionable, names the gap the discipline has to close, and maps the stages teams pass through on the way — including where most of them stall. The [Pillars](/docs/engineering/pillars) are the properties a delivery system needs before agentic execution pays off. [Guidelines](/docs/engineering/guidelines) and [Workflow](/docs/engineering/workflow) are the ttoss-specific layer: exactly how we implement all of it in this repository.
## Where This Sits Relative to the AI Section
The [AI section](/docs/ai) and this one describe the same shift at different altitudes, and the split is deliberate.
```mermaid
flowchart TB
P["Agentic Development Principlesthe laws that govern human-AI work"]
F["Agentic Engineering Foundationswhat must be true of a team"]
E["Engineering Pillarswhat we mechanized to make it true"]
G["Guidelines and Workflowhow ttoss does it, concretely"]
P --> F --> E --> G
```
[Agentic Development Principles](/docs/ai/agentic-development-principles) state what is true whether or not you act on it. [Agentic Engineering Foundations](/docs/ai/agentic-engineering-foundations) state the preconditions those laws impose on a team. This section is the layer below: the mechanisms we actually built, with real thresholds and real pipelines, and the reasoning that would let you build different ones.
Read top-down if you want to understand why the practices are shaped this way. Read bottom-up if you have a codebase to change on Monday.
---
## Breaking Changes
A breaking change is a cost we impose on every consumer of a package: they must read, understand, and act before they can take any other improvement we ship. That cost is sometimes worth paying. It is never free, and it is far more often avoidable than it first appears.
Declaring a break correctly is mechanical — a `BREAKING CHANGE:` footer, and `@lerna-lite/version` bumps the major. Deciding whether you should have one at all is the judgment this guideline covers.
## Separate the goal from its side effects
Most unnecessary breaks are not decisions anyone made. They fall out of _how_ a change was implemented, then get documented as though they were intended.
So enumerate every break the change introduces and ask of each one: **is this required by the goal, or incidental to the implementation?** Write the answer down. An incidental break is almost always avoidable, and you will not notice it is incidental unless you ask the question explicitly.
[#1171](https://github.com/ttoss/ttoss/pull/1171) is the worked example. The goal was to support a new MCP protocol revision. It arrived carrying four breaking changes, was documented thoroughly, and passed review on its own terms. None of the four were required by the goal. The one with the largest blast radius — arguments to a tool suddenly being validated — was a side effect of deleting an unrelated monkey-patch, and had not been recognised as a break at all.
```mermaid
flowchart TD
A[Change introduces a break] --> B{Required by the goal,or incidental?}
B -->|Incidental| C[Remove it:keep the old path alongside the new]
B -->|Required| D{How does it failfor a consumer?}
D -->|Loud: install, compile, test| E[Ship it and document it]
D -->|Silent: runtime, data-dependent| F[Make it opt-in,flip the default later]
```
## Classify breaks by how loudly they fail
Not all breaks cost the same, and the difference is not severity — it is **how a consumer finds out**.
| Fails at | Discovered by | Treatment |
| ------------------------- | ---------------------------- | ----------------------------------------------- |
| Install | Package manager, immediately | Ship it; the consumer cannot miss it |
| Compile | `tsc`, before merge | Ship it; the type error _is_ the migration note |
| Test | CI, before deploy | Ship it; document the fix |
| Runtime, on every request | First smoke test | Ship it with care |
| Runtime, on _some_ inputs | Production, eventually | Make it opt-in |
That last row is the one worth protecting against. A break that only fires on certain data survives code review, type checking, CI, and a manual smoke test, then fails for a real user weeks later. A consumer who reads the migration guide cover to cover can still miss it, because the guide cannot enumerate their data.
When strictness is the correct end state but would land silently, ship the mechanism disabled and let each consumer enable it once they have verified their own case. This is [Feature Flags](/docs/engineering/guidelines/feature-flags) reasoning applied to a package API: decouple shipping the capability from activating it. Flip the default in a later, deliberate major.
## Prefer an additive path over a replacement
When new behavior and old behavior can be distinguished at a boundary, serve both. Classify each request, input, or call at the edge, route old-shaped work down the existing path untouched, and route new-shaped work to the new implementation. Both can share the same underlying state and configuration, so the new capability costs consumers nothing.
This is usually cheaper than it sounds, and it converts a major release into a minor one. Be aware that a library's own convenience wrapper may not preserve the behavior you need — if it hardcodes an option you were relying on, own that branch yourself rather than accepting the regression as inevitable.
## Separate advertisement from enforcement
A contract that is merely **incomplete** becomes **wrong** the moment something starts enforcing it.
Schemas, types, and generated clients routinely describe less than what a system actually accepts — a field that may be sent as `null` to clear it, a property accepting several shapes, an optional argument nobody documented. While nothing validates against that description, the gap is invisible and harmless. Turn on validation and every gap becomes a rejected call that used to work.
So treat "what we publish to consumers" and "what we enforce on input" as separate decisions. Publishing a richer contract is safe and useful. Enforcing it is a behavior change that needs the loudness analysis above — and before enforcing anything generated, fix the generator so the contract describes reality.
## Verify against real consumers
Do not reason about whether a change breaks a consumer. Read the consumer's actual deployed contract and run it through the new code path.
Inference and empirical checks disagree more often than expected, and in the case above the empirical result was materially worse than the analysis: reading tool schemas off a live deployment showed the failure tracked a _documented, pervasive idiom_ rather than a handful of edge cases. That difference changed the decision. A short throwaway script against the real published dependency is worth more than any amount of careful reading.
## Divergence is evidence of an unstated invariant
When code diverges from a spec, a best practice, or the obvious simplification, treat it as evidence of an invariant nobody wrote down — not as a bug — until proven otherwise.
Workarounds attract deletion during upgrades, because the reason for them is rarely in a comment and often attributed to a dependency version that has since moved on. Before removing one, reproduce the problem it solved against the new version. In [#1171](https://github.com/ttoss/ttoss/pull/1171) a request-serialization queue looked like obsolete cruft from an old SDK; the constraint it worked around still existed, and removing it deadlocked under concurrent load. A hanging test was the only thing standing between that and production.
## When a break is genuinely necessary
Only once the steps above have failed to avoid it:
1. Add a `BREAKING CHANGE:` footer to the commit (see [How to version breaking changes?](https://github.com/ttoss/ttoss#how-to-version-breaking-changes) for the mechanics). A `!` in the type prefix works too; the footer carries the explanation.
2. Add a `MIGRATIONS.md` to the package, newest change first, covering only what requires consumer action. Show a diff for each change, and state the failure mode a consumer will observe if they miss it — not just what to edit.
3. Link it from the package `README.md`.
4. Cover the new behavior with tests, per [Tests](/docs/engineering/guidelines/tests). For a break that fails silently, the test asserting the _old_ behavior is the one that documents what you changed.
The presence of a `MIGRATIONS.md` should mean someone tried to avoid the break and could not. It is a last resort, not evidence of diligence.
---
## Feature Flags
# Feature Flags Guidelines
Feature flags enable controlled rollout of new features, instant rollback capability, and decoupled deployment from feature activation. Every new feature must implement feature flags as part of our systematic approach to reducing production bugs.
## When to Use Feature Flags
**Required for all new features** to enable:
- **Risk mitigation**: Instant disable without deployment
- **Gradual rollouts**: Test with subset of users first
- **A/B testing**: Compare feature performance
- **Decoupled deployment**: Ship code without activating features
## Implementation Patterns
### React Applications
Use `@ttoss/react-feature-flags` for React applications:
```tsx
const MyComponent = () => {
return (
);
};
```
### Backend Services
For backend implementations, use environment variables or configuration:
```typescript
const isFeatureEnabled = (featureName: string): boolean => {
return process.env[`FEATURE_${featureName.toUpperCase()}`] === 'true';
};
if (isFeatureEnabled('new_payment_processor')) {
// New implementation
} else {
// Existing implementation
}
```
## Best Practices
### Unique Entrypoints
Ensure all feature dependencies are contained within the feature flag boundary:
```tsx
// ✅ Correct: All dependencies inside feature flag
;
// ❌ Incorrect: Dependencies outside feature flag
const data = useMyNewComponentHook(); // Executes even when disabled
;
```
### Naming Conventions
- Use descriptive, kebab-case names: `new-checkout-flow`
- Include scope when needed: `admin-advanced-reporting`
- Avoid generic names: `feature-a`, `test-feature`
### Lifecycle Management
```mermaid
flowchart TD
A[Create Feature Flag] --> B[Development Testing]
B --> C[Staging Validation]
C --> D[Gradual Production Rollout]
D --> E{Feature Stable?}
E -->|Yes| F[Remove Flag & Cleanup]
E -->|No| G[Disable & Fix]
G --> C
```
1. **Development**: Create flag, implement feature
2. **Staging**: Validate with flag enabled
3. **Production**: Gradual rollout (5% → 25% → 50% → 100%)
4. **Cleanup**: Remove flag after stable period (typically 2 weeks)
## Integration with Development Process
### Pull Request Requirements
Every PR with new features must:
- Include feature flag implementation
- Document flag name and purpose
- Provide rollback plan via flag disable
### Code Review Checklist
- [ ] Feature flag implemented for new functionality
- [ ] Unique entrypoint pattern followed
- [ ] Fallback behavior defined
- [ ] Flag name follows conventions
- [ ] Documentation updated
### Deployment Strategy
- Deploy code with flag **disabled** by default
- Enable flag in staging for testing
- Gradual production rollout via configuration
- Monitor metrics during rollout
## Flag Management
### Configuration
Manage flags through:
- **Environment variables** for backend services
- **Configuration files** for frontend builds
- **Runtime configuration** for dynamic updates
### Monitoring
Track flag usage:
- **Activation rates**: Percentage of users seeing new feature
- **Error rates**: Compare flagged vs. unflagged implementations
- **Performance metrics**: Monitor impact of new features
### Cleanup Process
Remove flags after features are stable:
1. **Monitor period**: 2 weeks minimum after 100% rollout
2. **Remove flag logic**: Replace with direct implementation
3. **Update tests**: Remove flag-related test scenarios
4. **Documentation**: Update feature documentation
## Examples
### Simple Toggle
```tsx
const Dashboard = () => {
const showNewMetrics = useFeatureFlag('enhanced-metrics');
return {showNewMetrics ? => {
const token = await loadSocialToken({ userId, platform: 'tiktok' });
return tiktok.getValidToken(
{
accessToken: decryptValue({ ciphertext: token.accessToken, key: KEY }),
refreshToken: decryptValue({ ciphertext: token.refreshToken, key: KEY }),
accessTokenExpiresAt: token.accessTokenExpiresAt,
},
{
onRefresh: (updated) =>
saveSocialToken({
userId,
platform: 'tiktok',
accessToken: encryptValue({
plaintext: updated.accessToken,
key: KEY,
}),
refreshToken: encryptValue({
plaintext: updated.refreshToken,
key: KEY,
}),
accessTokenExpiresAt: new Date(Date.now() + updated.expiresIn * 1000),
}),
}
);
};
```
**Scheduled refresh** — a cron job refreshes tokens expiring within a wider window (default 6 hours) so connections stay alive even for users who are inactive. This guards against refresh tokens that themselves expire if never used. `findExpiringTokens` selects the records due for refresh.
```typescript
// jobs/tiktokTokenRefresher.ts — scheduled (e.g. hourly) by your deploy infra
export const tiktokTokenRefresher = async () => {
const tokens = findExpiringTokens(
await listSocialTokens({ platform: 'tiktok' })
);
for (const token of tokens) {
await getValidTikTokToken(token.userId).catch((error) =>
logRefreshFailure(token, error)
);
}
};
```
## 5. Internal token access (no user session)
Background scripts — a publish pipeline, an analytics sync — need a valid access token but run with **no user session**. Expose a system-authenticated endpoint that returns a fresh token for a given user, guarded by a service credential rather than a login. Sign that credential with `signJwt` from `@ttoss/auth-core` and verify it on the way in; never expose this endpoint publicly.
```typescript
router.post('/social/tiktok/internal-token', async (ctx) => {
const auth = ctx.headers.authorization?.replace('Bearer ', '') ?? '';
const claims = verifyJwt({
token: auth,
secret: process.env.SERVICE_JWT_SECRET!,
});
if (!claims || claims.aud !== 'internal') {
ctx.status = 401;
return;
}
const { userId } = ctx.request.body as { userId: string };
ctx.body = { accessToken: await getValidTikTokToken(userId) };
});
```
The job mints a short-lived service token with the matching secret and calls this endpoint — keeping provider tokens encrypted in one place and out of every background script.
## 6. Status and disconnect
The settings UI needs two more endpoints. `status` reports whether a connection exists and surfaces the `username` / `openId` for display (never the tokens). `disconnect` revokes the token with the provider when supported, then deletes the local record.
```typescript
router.get('/social/tiktok/status', async (ctx) => {
const token = await loadSocialToken({
userId: ctx.state.userId,
platform: 'tiktok',
});
ctx.body = token
? { connected: true, username: token.username }
: { connected: false };
});
router.delete('/social/tiktok/disconnect', async (ctx) => {
await revokeWithProvider(ctx.state.userId); // best-effort call to provider /revoke
await deleteSocialToken({ userId: ctx.state.userId, platform: 'tiktok' });
ctx.body = { connected: false };
});
```
## Summary
Build the provider `/authorize` URL with `state`, exchange the callback `code` for tokens, and store them **encrypted** per user and platform. Refresh both lazily (within a short window at call time) and on a schedule (within a wider window via cron), so tokens are always valid. Hand tokens to background jobs through a system-authenticated `internal-token` endpoint, and let the settings UI manage connection state through `status` and `disconnect`. Pair this with [MCP Server with OAuth](/docs/engineering/guidelines/mcp-server-oauth) when the same app must also _be_ an OAuth server.
---
## RDS PostgreSQL
In this tutorial, we will configure an AWS RDS PostgreSQL cluster.
In our case, we have multiples projects in multiples AWS accounts, and we wanted a single cluster to all projects.
## Networking
The cluster and the proxy are in a VPC whose CIDR is `10.0.0.0/16`.
To connect to the cluster, each other project has a VPC peering with the cluster VPC.
The rule for project's VCP CIDR is: `10.A.B.0/18`, in which `A` can vary from `1` to `255` (`A` equal `0` is the cluster VPC) and `B` can have 4 values (`0`, `64`, `128`, `192`). This way, each VPC has a range of `16,384` IPs.
Example of VPCs CIDR:
- VPC 1: `10.1.0.0/18`
- VPC 2: `10.1.64.0/18`
- VPC 3: `10.1.128.0/18`
- VPC 4: `10.1.192.0/18`
- VPC 5: `10.2.0.0/18`
- VPC 6: `10.2.64.0/18`
- ...
We need to define these ranges to avoid overlapping between VPCs when we create a VPC peering.
### Creating Peering
To create a peering, we need to request the peering from the project VPC to the cluster VPC.
The cluster VPC needs to accept the peering.
The peering name on the project VPC is `aurora-postgres-cluster-peering` and the peering name on the cluster VPC is `111122223333-aws-account-name-peering`.
Don't forget to update the route tables to allow the traffic between the VPCs. For all security groups associated with the Lambdas or EC2 instances, you need to update the router tables to allow the traffic to the cluster.
Allow the traffic from the project VPC to the cluster VPC on the security group of the proxy.
## Secrets
Save database role credentials in AWS Secrets Manager.
Create a `aurora-postgres-credentials/{role}` secret.
On proxy RDS, modify it to use the new secret.
---
## REST API
This document outlines the guidelines for building REST APIs.
## AWS Serverless Application Model
This guide is for building REST APIs with [AWS Serverless Application Model](https://aws.amazon.com/serverless/sam/).
### Project Structure
The project structure was inspired by [Next.js App Router routing](https://nextjs.org/docs/app/building-your-application/routing/route-handlers). We have a `src` directory that contains a folder named `api` where we define our API resources as folders and a file name `route.ts` ([following Next.js definition](https://nextjs.org/docs/app/api-reference/file-conventions/route)) that contains the methods for the resource .
Consider an API that has a CRUD operation for users with the endpoints:
- `GET /users` - Get all users
- `POST /user` - Create a user
- `GET /user/{id}` - Get a user by ID
- `PUT /user/{id}` - Update a user by ID
- `DELETE /user/{id}` - Delete a user by ID
The project structure would look like this:
```plaintext
.
├── src
│ ├── api
│ │ │ user
│ │ │ ├── {id}
│ │ │ │ ├── route.ts
│ │ │ ├── route.ts
│ │ ├── users
│ │ │ ├── route.ts
```
Each `route.ts` file contains the methods for the resource.
- `src/api/users/{id}/route.ts`
```typescript
export const GET: APIGatewayProxyHandler = async (event, context) => {
const id = event.pathParameters?.id;
// Get all users
};
export const PUT: APIGatewayProxyHandler = async (event, context) => {
const id = event.pathParameters?.id;
const body = JSON.parse(event.body || '{}');
// Update a user by ID
};
export const DELETE: APIGatewayProxyHandler = async (event, context) => {
const id = event.pathParameters?.id;
// Create a user
};
```
- `src/api/users/route.ts`
```typescript
export const GET: APIGatewayProxyHandler = async (event, context) => {
// Get all users
};
```
- `src/api/user/route.ts`
```typescript
export const POST: APIGatewayProxyHandler = async (event, context) => {
const body = JSON.parse(event.body || '{}');
// Create a user
};
```
### CloudFormation
Following [Carlin instructions](/docs/carlin/commands/deploy#lambda) to deploy resources with Lambda, you need to create your [AWS::Serverless::Function](https://docs.aws.amazon.com/pt_br/serverless-application-model/latest/developerguide/sam-resource-function.html) as follows in your template:
```yaml
AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31'
# Define all the common properties for all functions
Globals:
Function:
CodeUri:
Bucket: !Ref LambdaS3Bucket
Key: !Ref LambdaS3Key
Version: !Ref LambdaS3Version
Runtime: nodejs22.x
Resources:
ApiV1:
Type: AWS::Serverless::Api
Properties:
StageName: v1
UsersGETFunction:
Type: AWS::Serverless::Function
Properties:
Events:
ApiV1:
Type: Api
Properties:
Path: /users
Method: GET
RestApiId: !Ref ApiV1
Handler: api/users/route.GET
UserPOSTFunction:
Type: AWS::Serverless::Function
Properties:
Events:
ApiV1:
Type: Api
Properties:
Path: /user
Method: POST
RestApiId: !Ref ApiV1
Handler: api/user/route.POST
UserIdGETFunction:
Type: AWS::Serverless::Function
Properties:
Events:
ApiV1:
Type: Api
Properties:
Path: /user/{id}
Method: GET
RestApiId: !Ref ApiV1
Handler: api/user/{id}/route.GET
UserIdPUTFunction:
Type: AWS::Serverless::Function
Properties:
Events:
ApiV1:
Type: Api
Properties:
Path: /user/{id}
Method: PUT
RestApiId: !Ref ApiV1
Handler: api/user/{id}/route.PUT
UserIdDELETEFunction:
Type: AWS::Serverless::Function
Properties:
Events:
ApiV1:
Type: Api
Properties:
Path: /user/{id}
Method: DELETE
RestApiId: !Ref ApiV1
Handler: api/user/{id}/route.DELETE
```
:::note
Some points to consider about Carlin algorithm (you can check the documentation [here](/docs/carlin/commands/deploy#lambda)):
- The `LambdaS3Bucket`, `LambdaS3Key`, and `LambdaS3Version` are the S3 bucket, key, and version where Carlin uploads the Lambda code and adds them as [parameters](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html) in the CloudFormation template.
- The `Handler` property in the `AWS::Serverless::Function` resource is the path to the method in the `route.ts` file from `src/` and the method name separated by a dot.
:::
### Patterns
1. Use the `src/api` directory to define your API resources.
1. Create folders brackets `{}` to define dynamic routes. For example, `src/api/user/{id}/route.ts` will be the route for `GET /user/{id}`.
1. Use the `route.ts` file to define the methods for the resource.
1. Name your methods with the HTTP method in uppercase. For example, `GET`, `POST`, `PUT`, `DELETE`.
1. Use the `APIGatewayProxyHandler` type from `aws-lambda` to define the method signature.
1. Don't forget to install [`@types/aws-lambda`](https://www.npmjs.com/package/@types/aws-lambda).
1. It should be `APIGatewayProxyHandler` instead of `APIGatewayProxyHandlerV2` because of the [input format of a Lambda function for proxy integration](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format).
1. Use the `Globals` property to define common properties for all functions.
1. Name your CloudFormation function resources with the following pattern: `{ResourceName}{HTTPMethod}Function`. Examples:
1. `UsersGETFunction`: `GET /users`
1. `UserIdGETFunction`: `GET /user/{id}`
1. Name your `AWS::Serverless::Api` resources with the following pattern: `Api{StageName}`.
For example, if you have a stage named `v1`, the resource name should be `ApiV1`.
```yaml
Resources:
ApiV1:
Type: AWS::Serverless::Api
Properties:
StageName: v1
```
1. Name the `Events` property in the `AWS::Serverless::Function` resource with the name of your `AWS::Serverless::Api` resource. This is useful for cases in which you have multiple APIs in your template and want to use the same function for different APIs.
```yaml
Resources:
ApiV1:
Type: AWS::Serverless::Api
Properties:
StageName: v1
ApiV2:
Type: AWS::Serverless::Api
Properties:
StageName: v2
UsersGETFunction:
Type: AWS::Serverless::Function
Properties:
Events:
ApiV1:
Type: Api
Properties:
Path: /users
Method: GET
RestApiId: !Ref ApiV1
ApiV2:
Type: Api
Properties:
Path: /users
Method: GET
RestApiId: !Ref ApiV2
Handler: api/users/route.GET
```
---
## Technical Debt
Technical debt is often viewed solely as a negative consequence of poor engineering. However, at **ttoss**, we view technical debt as a financial instrument: **leverage**. When used consciously, it allows us to ship faster and learn earlier. When accumulated unconsciously, it becomes **entropy** that grinds development to a halt.
This guideline outlines our strategy for managing technical debt, grounded in [The Governance of Technical Debt](/docs/ai/agentic-development-principles/governance-of-technical-debt).
## The Philosophy of Managed Debt
We accept technical debt when it buys us **speed of learning** or **market timing**, provided that the debt is:
1. **Visible**: We know it exists.
2. **Contained**: It doesn't infect the entire system.
3. **Recoverable**: We have a plan to pay it down or discard it.
Unmanaged debt—sloppy code written without intent or boundaries—is not leverage; it is negligence.
## Systemic vs. Modular Debt
We distinguish between **Modular Debt** (acceptable) and **Systemic Debt** (unacceptable).
### Defining Systemic Technical Debt
**Systemic Technical Debt** is complexity that permeates the core data models, fundamental architecture, or shared business logic. It creates tight coupling between unrelated components, meaning a change in one area causes regressions in another. Unlike modular debt, systemic debt cannot be paid down incrementally; it often requires a full system rewrite.
### Avoiding Systemic Debt
To ensure debt remains modular and recoverable:
1. **Protect the Core**: Never compromise the integrity of your core domain models or database schemas for the sake of a quick UI fix.
2. **Strict Boundaries**: Enforce unidirectional data flow and strict architectural boundaries.
3. **Debt at the Edges**: Push "messy" code to the edges of the system (UI components, specific API adapters, scripts). Keep the center (Business Logic) clean.
## Strategies for Managing Debt
To ensure technical debt remains a tool rather than a trap, we apply the following strategies:
### 1. Modularization and Componentization
**Aligns with:** [The Principle of Contractual Specialization](/docs/ai/agentic-development-principles/governance-of-technical-debt#the-principle-of-contractual-specialization)
We structure our codebase into small, independent **packages**, **modules**, and **components**.
- **Why**: If a specific module is written quickly and becomes "messy," its boundaries prevent that mess from leaking into the rest of the system.
- **Strategy**: Prefer many small packages over large monoliths. If a package becomes unmaintainable, it should be cheap to rewrite or replace entirely because its surface area is small.
### 2. Automated Verification for Every Change
**Aligns with:** [The Corollary of Intrinsic Verification](/docs/ai/agentic-development-principles/governance-of-technical-debt#the-corollary-of-intrinsic-verification)
We never trade speed for correctness. Even "quick and dirty" code must be verified.
- **Why**: Invisible debt is the most dangerous kind. If code is messy but tested, we can refactor it safely. If it is messy and untested, it is a landmine.
- **Strategy**:
- Every Pull Request must include automated tests (Unit or E2E) covering the new functionality.
- CI/CD pipelines must pass before merging.
- "Hotfixes" must be accompanied by a regression test.
### 3. Isolation of Business Logic
**Aligns with:** [The Principle of Execution Isolation](/docs/ai/agentic-development-principles/governance-of-technical-debt#the-principle-of-execution-isolation)
We protect our core domain logic from the volatility of external tools, frameworks, and UI libraries.
- **Why**: Frameworks change, and UI trends shift. Your core business rules should not break when you upgrade a library.
- **Strategy**: Use adapters, hooks, or service layers to decouple "what the app does" (Business Logic) from "how it does it" (Implementation Details).
### 4. Observability as Interest Payments
**Aligns with:** [The Principle of Invisible Risk](/docs/ai/agentic-development-principles/governance-of-technical-debt#the-principle-of-invisible-risk)
If we choose to ship a sub-optimal solution to move fast, we must pay the "interest" in the form of higher observability.
- **Why**: We need to know immediately if our "hack" fails in production.
- **Strategy**: Add detailed logging, metrics, and alerts around debt-heavy areas. If you can't afford to monitor it, you can't afford to ship it.
### 5. Atomic State Decomposition
**Aligns with:** [The Principle of Atomic Debt Containment](/docs/ai/agentic-development-principles/governance-of-technical-debt#the-principle-of-atomic-debt-containment)
Break complex workflows into discrete, atomic steps.
- **Why**: It allows us to isolate "messy" logic to a single step in a process.
- **Strategy**: Design workflows as state machines or pipelines where each step has clear inputs and outputs. This makes it easy to swap out a specific step's implementation without rewriting the whole flow.
## Agent Instruction Example: Code Review
When using an AI agent to review code, you can use the following instruction template to ensure technical debt is managed effectively (change as needed for your context):
```markdown
**Role**: Senior Technical Reviewer
**Objective**: Review the provided code changes to ensure that any introduced technical debt is visible, contained, and verified.
**Instructions**:
1. **Critical Errors**: If you identify critical errors, provide a specific code suggestion to fix them.
2. **Checklist Evaluation**:
- For each item in the checklist below, determine if the condition is met.
- If met, mark as `[x]`.
- If NOT met, mark as `[ ]` and describe the missing part.
3. **Output**:
- Output the checklist with your evaluation.
- If all items are `[x]`, add "LGTM".
- Do not add unnecessary comments.
**Review Checklist**:
- [ ] **Verification**: The change includes automated tests covering new functionality and edge cases.
- [ ] **Containment**: The new logic is modular and does not leak implementation details into business logic.
- [ ] **Isolation**: If this is a "quick fix", it is isolated enough to be rewritten later without side effects.
- [ ] **Observability**: If the code is complex, there are sufficient logs/metrics to detect failure.
```
---
## Tests
This document outlines the guidelines for writing tests in ttoss packages.
## Quick Setup
For a fast automated setup, use the `@ttoss/monorepo` CLI tool to scaffold the complete test structure:
```bash
# Setup unit tests only (recommended for most packages)
npx @ttoss/monorepo setup-tests path/to/package
# Setup unit tests in current directory
npx @ttoss/monorepo setup-tests
# Setup both unit and e2e tests
npx @ttoss/monorepo setup-tests path/to/package --e2e
```
This command creates the directory structure, configuration files, installs required dependencies (`jest` and `@ttoss/config`), and adds test scripts to your `package.json`.
**After setup, verify everything is working:**
```bash
pnpm test
```
You should see a sample test pass. The setup creates a `setup.test.ts` file in `tests/unit/tests/` that you can delete once you start writing your own tests.
For manual setup or to understand the structure, continue reading the sections below.
## Runners
We use [Jest](https://jestjs.io/) as our test runner and [React Testing Library](https://testing-library.com/docs/react-testing-library/intro) for testing React components.
## Categories
We divide our tests into two categories: unit tests and e2e tests. Unit tests are for testing individual functions, and e2e tests are for testing the entire application.
We write unit tests in the `tests/unit/tests` folder and e2e tests in the `tests/e2e/tests` folder, both ending with the `.test.ts` or `.test.tsx` extension.
## File Structure
The inital file structure for tests in your package should be as follows:
```
tests/
e2e/
tests/
myFunction.test.ts
babel.config.cjs
jest.config.ts
unit/
tests/
myOtherFunction.test.ts
babel.config.cjs
jest.config.ts
tsconfig.json
jest.config.ts
```
## Manual Configuration
If you prefer to set up tests manually or need to customize the automated setup, follow these steps:
### Installation
First, install the required dependencies:
```bash
pnpm add -D jest @ttoss/config
```
For more details, see [@ttoss/config installation instructions](/docs/modules/packages/config/#jest).
### Configuration Files
1. Define the root Jest configuration in `jest.config.ts` at the package root. This sets up Jest [projects](https://jestjs.io/docs/configuration#projects-arraystring--projectconfig):
```ts
export default jestRootConfig({
coverageThreshold: {
global: {
lines: 50,
functions: 50,
branches: 50,
statements: 50,
},
},
});
```
2. Create a `jest.config.ts` file in `tests/unit/` for unit tests:
```ts
export default jestUnitConfig();
```
3. Create `tests/tsconfig.json` to enable TypeScript path aliases:
```json
{
"extends": "@ttoss/config/tsconfig.test.json",
"compilerOptions": {
"paths": {
"src/*": ["../src/*"],
"tests/*": ["./*"]
}
}
}
```
This way, you can import files from the `src` folder in your tests. For example:
```ts
```
4. (Optional) For e2e tests, create `tests/e2e/jest.config.ts`:
```ts
export default jestE2EConfig();
```
5. Create Babel configuration files for Jest transpilation. Add `tests/unit/babel.config.cjs` (and `tests/e2e/babel.config.cjs` if using e2e tests):
```js
const { babelConfig } = require('@ttoss/config');
const config = babelConfig({});
module.exports = config;
```
6. Add test scripts to `package.json`:
```json
{
"scripts": {
"test": "jest --projects tests/unit",
"e2e": "jest --projects tests/e2e"
}
}
```
### Running Tests
After setup, write your tests in `tests/unit/tests/` (and `tests/e2e/tests/` for e2e tests) with `.test.ts` or `.test.tsx` extensions.
Run unit tests:
```shell
pnpm test
```
Run e2e tests:
```shell
pnpm e2e
```
## Test Coverage Requirements
### Minimum Coverage Baseline
All packages must maintain **minimum 10% test coverage** as a baseline requirement. This ensures basic testing discipline while remaining achievable for all team members.
### Coverage Improvement Strategy
- **Package-specific goals**: Each package can set higher coverage targets based on complexity and criticality
- **Incremental improvement**: Increase coverage gradually when the team has capacity
- **Flexible timeline**: No rigid schedule—improve when sustainable for the team
- **Focus on critical paths**: Prioritize testing of core functionality and user flows
### Coverage Tracking
[@ttoss/config](https://ttoss.dev/docs/modules/packages/config/#jest) has already configured coverage collection.
### Integration with Pull Requests
- **Baseline maintenance**: PRs should not decrease overall package coverage below 10%
- **New feature testing**: New features should include appropriate test coverage
- **Coverage reporting**: Use coverage reports to guide testing priorities
---
## Automation
A check a human runs by hand does not exist to an agent.
This is the entire pillar. An agent cannot consult a wiki page it was not given, cannot infer a convention enforced only in review, and cannot ask whether this is one of the cases where the team makes an exception. It can run a command and read the output. Everything you want it to respect has to be reachable that way, or it is not a rule — it is a hope.
Automation is therefore not the productivity pillar. It is the pillar that makes the others enforceable, which is why it sits underneath both [Tests](/docs/engineering/pillars/tests) and [Complexity Reduction](/docs/engineering/pillars/complexity-reduction).
## Two Properties That Matter
**Machine-runnable from a fresh checkout.** One command, no undocumented setup, no "you also need to have the staging credentials exported". This is what lets an agent close its own loop: run the checks, read the failure, fix, run again. An agent that cannot run the checks must route every attempt through a human, which reinstates the bottleneck agents were supposed to remove. Reproducible environments are part of this pillar, not an infrastructure nicety.
**Mechanically blocking.** A warning is not a rule. If violating a constraint still allows the merge, the constraint is behavioral, and behavioral constraints are honored probabilistically — fine for style, useless for anything with an asymmetric downside. The distinction is developed further in [Deterministic Guardrails](/docs/ai/agentic-engineering-foundations/deterministic-guardrails).
## How This Works at ttoss
Our pull request pipeline is a single script, and its shape encodes a few decisions worth stealing.
```mermaid
flowchart LR
L["lint(must be a no-op)"] --> S["dependencyversion check"]
S --> B["i18n, build, testchanged packages + dependents"]
B --> D["deploy preview+ report on the PR"]
```
**Lint runs, and CI fails if it changed anything.** The pipeline does not format your code for you. It runs the formatter and then refuses the build if the working tree is now dirty, on the grounds that committed code should already have been correct. This turns formatting from a negotiation into a fact, and it means an agent's output is held to exactly the same standard as a human's, with no reviewer spending attention on it.
**The blast radius is computed, not guessed.** Tests and builds run with turbo's `--filter=...[main]`, which selects every package changed since main _and every package that depends on them_. Change a component and the packages consuming it get tested too. Nobody has to know the dependency graph, which matters most when the author of the change is an agent that cannot be trusted to reason about repository topology it was never shown.
**Every pull request deploys.** Preview environments are provisioned by [carlin](/docs/carlin), and the deploy outputs are posted back as a comment on the pull request. This is what makes higher-level validation possible at all — the outer loops described in [Tests](/docs/engineering/pillars/tests) need something real to run against, not a local mock.
**Publishing is a consequence of merging.** The main branch versions, publishes and deploys on its own. Nobody decides to release, which removes the human step where batches accumulate.
## Failure Mode
The team has a convention — say, that recipes carry only color tokens — and it lives in a review checklist. Every human eventually internalizes it. Every agent violates it on first contact, because the rule was never in a form the agent could consume, and reviewers become the enforcement mechanism for something a linter could have caught.
The fix is not a better prompt. It is a lint rule, a type, or a gate — after which the agent complies on every task, forever, and no reviewer spends attention on it again. Repository instruction files help agents cooperate, but they are advisory; only the pipeline is binding.
---
## Complexity Reduction
Complexity has always been charged to the next person who reads the code. With agents it is charged twice, and the second charge is the one teams miss.
The first charge is comprehension. Whoever validates a change has to understand the code around it, and with agent-authored diffs that person did not write it — so they pay the full cost of understanding without the head start that writing gives you. The second charge is replication. Agents infer conventions from the code they are shown, so complexity is not merely inherited by the next task; it is reproduced by it. A codebase with one tangled module gets more tangled modules, because the tangle is now the example. [The Principle of Pattern Inertia](/docs/ai/agentic-development-principles/physics-of-ai-integration#the-principle-of-pattern-inertia) describes the mechanism.
There is also a hard limit that has no equivalent for humans. A human facing an incomprehensible module can spend three days and eventually understand it. An agent facing a task whose smallest correct context exceeds its working context does not get slower — it guesses, confidently. Complexity therefore converts directly into wrong output rather than into delay.
## Why a Budget and Not a Guideline
"Keep functions simple" is advice, and advice is applied unevenly by humans and probabilistically by agents. A threshold enforced by the linter fails the build, fails identically for everyone, and costs no reviewer attention to apply — the same reason [Automation](/docs/engineering/pillars/automation) insists that a rule not enforced by a machine is not a rule. The value is not that any single threshold is optimal. It is that the constraint stops depending on whoever happens to be reviewing.
## What the Budget Bounds
Our shared lint configuration puts a ceiling on each dimension that makes code expensive to hold in your head: the number of independent paths through a function, its cognitive complexity, how deeply control structures and callbacks nest, how many parameters a function takes before an object is required, and how long a function or file may grow. The current values live in `@ttoss/eslint-config` and are deliberately not repeated here — they move as the codebase does, and the configuration is the source of truth.
Cyclomatic complexity and [cognitive complexity](https://www.sonarsource.com/blog/cognitive-complexity-because-testability-understandability-and-changeability-matter/) are both bounded because they measure different things. The first counts paths and treats a flat switch statement as complex; the second weights nesting, so it tracks how hard code is to hold in your head. A long flat function is usually fine. A short deeply nested one usually is not.
Alongside the size budget sits a set of duplication and dead-code rules — identical functions, duplicated branches, dead stores, collapsible conditionals. These matter more in agentic work than they used to: generating a near-copy of an existing function is cheaper than finding it, so an agent will happily produce the fourth variant of something that should have one implementation. Duplication detection is how that tendency gets caught mechanically instead of in review.
## Calibrate Thresholds From Your Own Distribution
What makes this pillar work is not any particular number. It is the method: every threshold is picked by measuring the repository's actual distribution and setting the limit where only genuine outliers report.
The test-file overrides show what the method produces. When we last calibrated them, the source file-length limit flagged dozens of suites while a limit two and a half times higher flagged only the handful that were genuinely unwieldy; a relaxed path-complexity limit reported exactly two files, both real; and the callback-nesting limit had to rise by two because `describe > describe > test > callback` is the standard shape of a suite, not a defect in one.
Two rules are off entirely in tests, for reasons no threshold fixes. Function-length counts a `describe` callback as one function, so it measures a whole suite as a single unit — the unit is wrong, not the limit. And identical-function detection fights the near-identical arrange/assert blocks that are how a readable suite is written in the first place.
What is deliberately _not_ relaxed says the most: `max-depth`, `max-params` and `sonarjs/cognitive-complexity` keep their source limits in test files, because they report zero violations there. Nothing about test code makes deep nesting or parameter soup legitimate.
The lesson generalizes. A threshold calibrated to a real distribution is one every violation is worth reading. A threshold picked by taste produces hundreds of reports, and hundreds of reports produce blanket `eslint-disable` comments — at which point the constraint is gone and the file still looks compliant.
## Failure Mode
The code compiles, the tests pass, and every task requires loading three modules to change one line. Agents guess, because the smallest correct context no longer fits. Reviewers approve, because reconstructing the reasoning costs more than trusting it. Nothing in the pipeline distinguishes this from a healthy system until an incident reveals that nobody — human or agent — understood the change that caused it.
---
## Pillars
A pillar is not a practice. It is a property the delivery system has, together with the mechanism that makes it true whether or not anyone remembers to care.
That distinction is the whole point. "We write tests" is a practice, and practices decay under deadline pressure. "Coverage cannot decrease, and the pipeline refuses the merge if it does" is a mechanism, and mechanisms hold when attention does not. Agents make the difference urgent: an agent has no institutional memory, no fear of the reviewer who caught it last time, and no ability to feel that a shortcut is beneath the team's standards. It complies with what is enforced and interpolates the rest.
## The Three We Have Mechanized
```mermaid
flowchart TB
A["Automationif a machine cannot run it,it is not enforced"]
T["Testsverification is the loopthat makes generated code committable"]
C["Complexity Reductiona budget on how much must beunderstood to change anything"]
A --> T
A --> C
```
**[Automation](/docs/engineering/pillars/automation)** comes first because the other two depend on it. A rule a human applies by hand does not exist to an agent, and a check that only runs on someone's laptop cannot be part of a feedback loop.
**[Tests](/docs/engineering/pillars/tests)** is where the agentic shift bites hardest. When code volume multiplies, reviewing every change stops being a strategy, and the team has to decide deliberately where its validation sits rather than defaulting to the loop it inherited.
**[Complexity Reduction](/docs/engineering/pillars/complexity-reduction)** is the least obvious and the most compounding. Agents replicate whatever patterns dominate the code they read, so complexity is not merely inherited by the next human — it is amplified by the next task.
## What These Pillars Are Not
They are not the complete set. [Agentic Engineering Foundations](/docs/ai/agentic-engineering-foundations) defines six preconditions for agentic work, and these three cover part of that ground: Automation and Tests together serve Testability and the enforcement half of Deterministic Guardrails, and Complexity Reduction serves Understandability.
The remaining foundations have no page here yet, which is a statement about our own maturity rather than about their importance:
- **Executable Intent** — we do this in practice, through acceptance criteria and typed contracts, but we have not reduced it to a mechanism worth documenting as a pillar.
- **Observability** — partially covered by service-level practice, not yet by a standard every package meets.
- **Reversibility** — the closest we have is mechanized in [feature flags](/docs/engineering/guidelines/feature-flags) and [breaking changes](/docs/engineering/guidelines/breaking-changes), plus trunk-based development and continuous deployment.
- **Deterministic Guardrails** — scoped agent permissions and graduated autonomy are still convention here, not structure.
A team building this from scratch should read the foundations for the full set of properties, and these pages for what mechanizing three of them actually looks like.
---
## Tests(Pillars)
Borrow a frame from systems engineering: the codebase is the plant, and every mechanism that inspects its output is a sensor in a feedback loop. Code review is one such sensor. It is not the only one, and treating it as the default is what breaks when agents enter the system.
A real system has many subsystems — payments, login, dashboard, form submissions, cron jobs — and historically the team put a sensor on each one at the lowest possible layer: a human reading the diff. That worked because it had to. Before AI, the only way to make the plant produce faster was to hire more people, and each new person arrived with review capacity attached. Throughput and review capacity grew together.
That coupling is now broken. A team can multiply the code it produces without adding a single reviewer, and the old process quietly becomes the constraint.
## The Choice Nobody Makes Explicitly
So ask the question directly, because defaulting is also a choice: do you keep reviewing every change — accepting that your throughput is capped at reviewer hours, and forgoing most of what agents offer — or do you find other ways to establish that the system is correct?
Two moves make the second option real.
**Review only what is genuinely critical.** Schema migrations, authentication, anything touching money, anything irreversible. The point is not that other code matters less; it is that human attention is the scarcest sensor you have and should be pointed where failure is least recoverable. If your entire system is critical, you do not have many options — and knowing that is itself valuable, because it tells you your ceiling is real rather than accidental.
**Elevate the loop.** Instead of reviewing each subsystem at the diff level, validate at a higher layer: end-to-end tests, contract tests, integration suites running against a real deployed environment. The time that would have gone into reviewing one subsystem instead buys evidence about the whole system, on every change, forever.
```mermaid
flowchart TB
subgraph P["Codebase — the plant"]
direction LR
S1["Payments"]
S2["Login"]
S3["Dashboard"]
S4["Cron jobs"]
end
I["Intent"] --> AG["Agent"]
AG --> CH["Change"]
CH --> P
P --> IL["Inner loopcode review, unit testsone subsystem at a time"]
P --> OL["Outer loope2e, contract tests, telemetrythe whole system at once"]
IL -.->|"scales with reviewer hours"| AG
OL ==>|"scales with the system,not with headcount"| AG
```
The dotted arrow is the one that runs out. The thick one is the one worth investing in, because its cost is paid once per test and its value is collected on every future change.
## The Part That Is Easy to Get Wrong
Elevating the loop is not the same as loosening the inner one and hoping. If you stop reviewing a subsystem and do not build the outer loop that now covers it, you have not moved validation up — you have removed it. The teams that extract the most value from AI are not the ones that review least; they are the ones whose outer loops are strong enough that reviewing less becomes a defensible decision.
Two properties determine whether an outer loop can carry that weight.
**Latency.** Outer loops are slower and coarser by nature. An e2e suite tells you something is broken; it rarely tells you which line. That is an acceptable trade only when the loop is fast enough to run on every change, which is why suite speed is a correctness concern and not a convenience. A loop that runs nightly is not a loop an agent can iterate against.
**Determinism.** A flaky outer loop is worse than no outer loop, because it trains the team to ignore the only sensor still watching. When a failure sometimes means nothing, it soon means nothing. Every quarantined flake is a hole in the layer you just decided to depend on.
The loop also extends past the merge. Tests verify what the team predicted; telemetry verifies what it did not, which matters more when the person approving a change never built the mental model that writing it would have produced. See [Observability](/docs/ai/agentic-engineering-foundations/observability) for that half.
## How This Works at ttoss
The mechanism that keeps verification from eroding is the coverage ratchet: every package pins its coverage threshold, and the threshold may never be lowered. Change code, and you raise the threshold to match — upward only. This matters specifically because generated code accumulates faster than anyone audits it, and coverage that is merely observed drifts down one merge at a time. Coverage that is pinned cannot.
Every pull request also gets a real deployed environment, courtesy of the pipeline described in [Automation](/docs/engineering/pillars/automation). That is what gives outer-loop tests something honest to run against.
Frameworks, scaffolding, and mocking conventions live in the [tests guideline](/docs/engineering/guidelines/tests) — they change; the ratchet and the real environment do not.
## Failure Mode
An agent produces a week's worth of code in a day. The team keeps its inherited process and reviews all of it at the diff level. The queue grows, reviewers start skimming, and a skimmed approval looks exactly like a careful one. The regressions that follow are attributed to the agent. The sensor was at the wrong layer for the volume flowing through it.
---
## Why Software Engineering Is Changing
Every tooling wave in software has been sold as a paradigm shift, and most were not. The argument for treating this one differently is not that agents write code well. It is that they change which part of the delivery system is scarce, and scarcity is what determines how a discipline organizes itself.
## Complexity Transfers, It Does Not Disappear
Each generation of software delivery moved complexity away from the person receiving the value and toward the party better equipped to absorb it.
```mermaid
flowchart LR
S1["Local softwarethe user managesinstallation and upkeep"]
S2["Software as a servicethe vendor managesinfrastructure"]
S3["Agents as a servicethe agent managesunderstanding and execution"]
S1 --> S2 --> S3
```
Installed software made the end user responsible for keeping it running. SaaS moved that to the vendor, and users stopped thinking about servers. Agents apply the same move one layer up: the artifact itself becomes optional. Where the chain used to run _AI → software → result_, it can now run _agent → result_, with code generated as ephemeral tooling in service of an outcome rather than shipped as a durable product.
The observation underneath is about limits, not convenience. Traditional systems require a human to pre-encode decision rules for every situation the human anticipated, and the number of interaction paths in a system grows exponentially with its components while human working memory does not grow at all. Agentic systems decouple solution capability from that fixed ceiling, because the reasoning is done by a model whose capacity scales with compute rather than with anyone's head.
You do not have to accept the strong version of this — that software artifacts largely disappear — for the consequence to hold. Even in the weak version, the artifact stops being the thing engineers primarily produce.
## Why Isolated Success Does Not Transfer
A benchmark isolates a task: one issue, a clean starting state, a clear success condition. Production software is the opposite — a long-lived system where today's change interacts with years of prior decisions, most of them unwritten. Whatever the model, that distinction is structural. Performance on isolated tasks says little about performance on continuous work, because the second depends on context the task itself does not contain.
This is why the argument for engineering rigor does not rest on any current weakness of the models. Even a generator that were never wrong about the task in front of it would still be wrong about the system around it whenever that system's constraints were unavailable to it — and no model can see a constraint nobody wrote down. What closes the distance between isolated success and continuous reliability is the system the agent operates inside: whether mistakes surface quickly, whether context survives between tasks, whether damage stays bounded.
An organization that adopts agents without building that system gets the volume of a strong model and the reliability of its weakest loop.
## The Steps of Adoption
Teams do not adopt agents in one move. They pass through recognizable steps, and each is defined less by the tools in use than by two things: how many agents one engineer can keep productive — roughly an order of magnitude more at each step — and what is currently the bottleneck. The human role moves up the stack at every step — pair, then orchestrator, then manager of managers, then someone steering by intent — and it is elevation rather than removal, the same conclusion [The Principle of Role Elevation in Human-AI Hybridization](/docs/ai/agentic-development-principles/symbiosis-of-human-ai-agency#the-principle-of-role-elevation-in-human-ai-hybridization) reaches from a different direction.
```mermaid
flowchart LR
S0["0 · Gatedaccess is the blocker"]
S1["1 · Assistedone engineer, one agent"]
S2["2 · Parallelone engineer, many agents"]
S3["3 · Supervised autonomyagents starting agents"]
S4["4 · AI-nativesteer by intent"]
S0 --> S1 --> S2 --> S3 --> S4
```
| Step | Your role | What it looks like | The bottleneck |
| ----------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0 · Gated | Blocked | Access to capable models is gated or process-heavy, and nothing an agent produces has a sanctioned place to live. | Legacy approval processes, cost containment instead of outcomes, and no technical voice where the decisions are made. |
| 1 · Assisted | Pair | One engineer, one agent, mostly supervised. You run one session at a time and review almost every change before it merges. An afternoon's task becomes something finished between meetings. | Your attention. With low trust in the output and no self-verification, you read everything and never look away. Work is synchronous. |
| 2 · Parallel | Orchestrator | One engineer runs several agents, each in its own isolated checkout. Each agent checks its own work — tests, build, lint, security — before you see it. You review final diffs, not keystrokes, and the agent writes most of the code. A backlog that took the team weeks becomes one engineer's afternoon. | Reviewing output. You write less and check several streams instead, and steering that many sessions costs attention of its own. |
| 3 · Supervised autonomy | Manager of managers | Agents write nearly all the code, and some of it proactively — maintenance that used to wait for someone to find time now runs continuously. "Did you read the code?" becomes "what context was the model missing, and how do we fix that for next time?" | Trust in the loop, and the team's decision throughput. The trap is scaling agent count before the loop has earned the trust to justify it. Cost per unit of work becomes something to manage. |
| 4 · AI-native | Steering by intent | The loop is fully closed and most agents are started by other agents. You steer by intent and monitor by exception. A quarter-long migration becomes a workflow you kick off and check on. | Identifying which work to automate at scale, and enforcing the right guardrails for each kind of work. |
Two of the transitions carry most of the engineering weight.
**From Assisted to Parallel** is where this section's [Pillars](/docs/engineering/pillars) enter. The unlock is a self-verification loop you trust — tests, build, lint, and end-to-end checks against a real development environment — plus automated review, so the agent's work is verified before a human sees it and routine actions no longer wait on a human to approve them. Without that loop, running more agents multiplies the reading rather than the output. It cannot be bought: the work is in your own codebase and pipeline. [Tests](/docs/engineering/pillars/tests) is about exactly this moment.
**From Parallel to Supervised autonomy** is about context and authority. Agents need a way to pull in what they lack — code, decisions, discussions — rather than having it re-explained per task, which is the concern of [Understandability](/docs/ai/agentic-engineering-foundations/understandability). Work has to be decomposed into loops and routines an agent can start for another agent, and agents will touch code owned by other teams, so review speed and edit rights become organizational questions. What keeps this safe is not trust in the model but structural bounds on what each agent may reach — [Deterministic Guardrails](/docs/ai/agentic-engineering-foundations/deterministic-guardrails). Throughout, one rule does not change: the same quality bar applies to human and agent-generated code.
Read the steps as a map of bottlenecks rather than a ladder to climb quickly. A team that skips the building does not skip the step; it arrives at the next one with the previous bottleneck still in place, now hidden. "We use AI to write code faster" optimizes step 1 while the roles worth having belong to steps 2 and beyond.
---
## Engineering Development Process
This document describes the engineering development process, focused on technical implementation and software delivery. For the product development process (strategy, discovery, and feature definition), see the [product workflow](/docs/product/workflow).
## Overview
Our engineering development process is based on agility and velocity, following the principles described in [First, We Aim for Velocity](/blog/2024/12/17/first-we-aim-for-velocity-driving-fast-and-adaptive-product-development). We use **Trunk-Based Development** as our branching model to ensure continuous integration and rapid deliveries.
## Development Workflow
```mermaid
flowchart TD
A[Task AssignmentFrom Product Workflow] --> B[Create Feature Branchfrom main]
B --> C[Local DevelopmentFollowing Guidelines]
C --> D[Create Pull RequestSmall & Daily]
D --> E{PR Requirements Met?}
E -->|No| F[Update PR- User Flow Testing- Feature Flags- Test Coverage]
F --> E
E -->|Yes| G[Ephemeral DeployAutomatic CI/CD]
G --> H[Code ReviewMandatory Approval]
H --> I{Review Approved?}
I -->|No| J[Address Feedback]
J --> H
I -->|Yes| K[Squash Merge to main]
K --> L[Staging DeployAutomatic]
L --> M[Tag CreationIf Successful]
M --> N[Production DeployAutomatic]
N --> O[Developer Monitoring30min minimum]
O --> P{Issues Detected?}
P -->|Yes| Q[Fix or Rollback]
P -->|No| R[Task Complete]
```
## Development Process
### Task Assignment
Tasks come from the [product workflow](/docs/product/workflow) with defined requirements, acceptance criteria, and priority.
### Local Development
#### Trunk-Based Development
We follow the [Trunk-Based Development](https://trunkbaseddevelopment.com/) model, where:
- **Main branch (`main`)**: Always contains stable code ready for production
- **Feature branches**: Short-lived branches (maximum 1-2 days) created from `main`
- **Frequent integration**: Small and frequent commits to the main branch
#### Creating Pull Request
1. **Create branch** from `main`:
```bash
git checkout main
git pull origin main
git checkout -b feature/feature-name
```
2. **Develop** following our [coding practices](/docs/engineering/guidelines)
3. **Create Pull Request** on GitHub when the feature is ready
#### Pull Request Requirements
Every PR must include:
- **User Flow Validation**: Complete the PR template checklist confirming which user flows were tested
- **Size Limitation**: PRs should be small and focused (ideally daily submissions)
- **Feature Flags**: New features must use [feature flags](/docs/engineering/guidelines/feature-flags) for controlled rollout
- **Test Coverage**: Maintain or improve package test coverage baseline
#### Small Daily Pull Requests
To ensure thorough code review and faster feedback:
- **Maximum one PR per developer per day**
- **Focus on single functionality** or bug fix
- **Limit scope** to 200-400 lines of code when possible
- **Break large features** into smaller, incremental changes
- **Frequent integration** reduces merge conflicts and review complexity
### 3. Ephemeral Deploy & Code Review
Each PR automatically gets an ephemeral deploy for testing before mandatory code review approval.
### 4. Deployment Pipeline
After merge to `main`: **Staging Deploy** → **Tag Creation** → **Production Deploy**
All deployments are automated through GitHub Actions.
## Developer Responsibilities
**Post-Deploy Monitoring**: Monitor production for 30+ minutes after deployment. Fix issues quickly or rollback if necessary.
**Complete Ownership**: Responsible for the entire cycle from development through post-deployment support.
## Tools and Technologies
- **GitHub Actions**: CI/CD automation
- **Ephemeral deploys**: Temporary PR environments
- **Monitoring**: Centralized logs, metrics, and alerts
- **Communication**: Slack (alerts), GitHub (reviews), ClickUp (tasks)
## Core Principles
- **Velocity with Quality**: Fast cycles, continuous testing, small incremental changes
- **Shared Responsibility**: Developer autonomy with full accountability from code to production
- **Continuous Improvement**: Regular retrospectives and process adaptation
## Product Integration
This engineering workflow integrates with the [product workflow](/docs/product/workflow) at the following points:
- **Task assignment**: Tasks defined in the product process
- **Implementation feedback**: Technical feedback on feasibility and effort
- **Delivery validation**: Confirmation that product criteria have been met
- **Metrics monitoring**: Tracking of KPIs defined by product
For more details on how tasks are created and prioritized, see the [product documentation](/docs/product/workflow).
---
## Goals
## Engineering Workflow Goals
The main objective of our engineering workflow is to implement technical solutions efficiently, maintaining high quality and delivery velocity. Our specific goals are:
### Velocity and Agility
- **Fast development cycles**: Enable multiple deployments per day when necessary
- **Fast feedback**: Identify problems as early as possible in the process
- **Bottleneck reduction**: Minimize waiting time between development and production
### Quality and Reliability
- **Reviewed code**: All code goes through review before production
- **Automated testing**: Ensure functionality through testing
- **Continuous monitoring**: Monitor applications in production
### Autonomy and Responsibility
- **Autonomous developers**: Ability to make technical decisions
- **End-to-end responsibility**: Monitor code from development to production
- **Continuous improvement**: Constant process evolution based on learnings
### Efficient Integration
- **Trunk-Based Development**: Continuous integration with main branch
- **Automated deployment**: Reduction of manual intervention in deployments
- **Effective collaboration**: Facilitate team communication and collaboration
### Separation of Responsibilities
This engineering workflow focuses specifically on **technical implementation**, while the [product workflow](/docs/product/workflow) handles **strategy and definition** of features. This separation allows:
- **Specialization**: Each team focuses on their area of expertise
- **Role clarity**: Well-defined responsibilities
- **Efficiency**: Processes optimized for each context
- **Natural integration**: Clear connection points between product and engineering
---
## Engineering Workflow
Welcome to the ttoss engineering workflow documentation. This workflow is specifically focused on **technical implementation** and **software delivery**, complementing the [product workflow](/docs/product/workflow) which handles strategy and feature definition.
## Overview
Our engineering process is based on agility and velocity principles, as described in [First, We Aim for Velocity](/blog/2024/12/17/first-we-aim-for-velocity-driving-fast-and-adaptive-product-development). We use modern practices like **Trunk-Based Development** and **Continuous Deployment** to ensure fast and reliable deliveries.
## Workflow Structure
### 1. [Goals](./goals)
Objectives and principles that guide our technical development process.
### 2. [Development Process](./development-process)
Detailed process from task assignment to production monitoring.
## Differences Between Product and Engineering Workflows
| Aspect | Product | Engineering |
| -------------------- | ------------------------------------------ | ---------------------------------- |
| **Focus** | Strategy, discovery, definition | Technical implementation, delivery |
| **Responsibilities** | What to build, why to build | How to build, when to deliver |
| **Tools** | ClickUp, user research, analysis | GitHub, CI/CD, monitoring |
| **Outputs** | User stories, requirements, prioritization | Code, deployments, features |
| **Metrics** | Product KPIs, user satisfaction | Cycle time, code quality |
## Integration Points
The workflows connect at specific moments:
- **Task assignment**: Engineering receives tasks defined by product
- **Technical feedback**: Engineering informs about feasibility and effort
- **Delivery validation**: Confirmation that product criteria were met
- **Metrics monitoring**: Joint tracking of KPIs
## Next Steps
For developers starting the process:
1. Read the [Goals](./goals) to understand the principles
2. Study the [Development Process](./development-process) for the complete process
3. Review the [Pillars](/docs/engineering/pillars) that this workflow depends on
## Related Links
- [Product Workflow](/docs/product/workflow) - Product development process
- [Engineering Guidelines](/docs/engineering/guidelines) - Code standards and practices
- [Pillars](/docs/engineering/pillars) - Properties this workflow relies on
---
## Examples
showNotification('Success!')}>
{t('buttons.submit')}
```
This approach creates:
- **Prop drilling** through multiple component levels
- **Repetitive code** in every component
- **Tight coupling** between components and applications
- **Difficult maintenance** when changing themes or languages
## The ttoss Solution
**Configure once at the root, integrate automatically everywhere.**
```tsx
// ✅ ttoss approach - configure once
function App() {
return (
{/* All ttoss packages automatically use:
- Bruttal theme for styling
- Portuguese translations
- App notification system */}
);
}
```
## Foundation Packages
ttoss packages rely on foundation systems that work through React Context. These packages provide core functionality that other packages consume automatically:
### 1. Theme & Styling
**Packages**: `@ttoss/theme`, `@ttoss/ui`, `@ttoss/components`
Components automatically access theme tokens without props:
```tsx
export const MyComponent = () => (
Click me
);
```
**No theme prop needed** - components consume the theme from context.
### 2. Internationalization
**Package**: `@ttoss/react-i18n`
Components access translations through hooks:
```tsx
export const MyComponent = () => {
const { intl } = useI18n();
return (
{intl.formatMessage({
defaultMessage: 'Welcome',
description: 'Welcome message',
})}
);
};
```
**No message props needed** - translations come from context.
### 3. Notifications
**Package**: `@ttoss/react-notifications`
Components trigger notifications through hooks:
```tsx
export const MyComponent = () => {
const { notify, setLoading } = useNotifications();
const handleAction = async () => {
setLoading(true);
try {
await saveData();
notify({ type: 'success', message: 'Saved!' });
} finally {
setLoading(false);
}
};
return (
<>
Save
);
};
```
**No notification props needed** - notification system comes from context.
### Additional Foundation Packages
The foundation layer continues to grow:
- **`@ttoss/forms`**: Form management with validation, leveraging theme and i18n
- **`@ttoss/react-icons`**: Icon system integrated with themes
- **More to come**: As the ecosystem evolves, new foundation packages extend the capabilities
All foundation packages follow the same principle: **configure once, integrate everywhere**.
## Real-World Example: Authentication
The `@ttoss/react-auth-core` package demonstrates this pattern perfectly:
```tsx
// Package implementation
export const AuthSignIn = ({ onSignIn }) => {
const { intl } = useI18n();
const { isLoading } = useNotifications();
return (
{intl.formatMessage({ defaultMessage: 'Sign in' })}
{intl.formatMessage({ defaultMessage: 'Sign in' })}
);
};
```
Notice:
- ✅ Uses `useI18n()` hook - no message props
- ✅ Uses `sx` prop with tokens - no style props
- ✅ Uses `useNotifications()` hook - no loading props
## Key Benefits
### 1. Zero Configuration for Packages
Each ttoss package works immediately once you set up root providers:
```tsx
// Just wrap your app once
{/* Every ttoss package now works perfectly */}
```
### 2. Flexible Customization
Change everything from one place:
```tsx
// Switch from English to Portuguese
// Switch from Bruttal to Oca theme
// Custom notification behavior
```
### 3. Clean Component APIs
Components have minimal, focused props:
```tsx
// Only business logic props - no UI configuration
{children}
);
render(
>(
() => ({
subscription: farmNotificationSubscription,
variables: { farmId }, // AppSync filters: only events with this farmId are delivered
onNext: (data) => {
console.log('Received notification:', data?.onFarmNotification);
},
onError: (error) => {
console.error('Subscription error:', error);
},
}),
[farmId]
);
useSubscription(config);
return null;
};
```
> **Relay compiler:** run `relay-compiler` after updating the schema so it generates the `__generated__/FarmNotificationSubscription.graphql.ts` file with TypeScript types. Your Relay `Network` must also be configured with a WebSocket `subscribeFunction` that connects to the AppSync real-time endpoint.
### Triggering subscriptions from a Lambda with AWS IAM
When a backend Lambda triggers a mutation to push a real-time event, AppSync needs to authorize that call. **AWS IAM** is the recommended approach: the Lambda's execution role is granted `appsync:GraphQL` permission and AppSync trusts the AWS Signature V4 request.
See the [AWS documentation on multiple authorization types](https://aws.amazon.com/blogs/mobile/using-multiple-authorization-types-with-aws-appsync-graphql-apis/) for background.
1. **Enable `AWS_IAM` as an additional authentication provider** in `createApiTemplate`:
```typescript
const template = createApiTemplate({
schemaComposer,
additionalAuthenticationProviders: ['AWS_IAM'],
noneDataSourceResolvers: [
{ typeName: 'Mutation', fieldName: 'publishFarmNotification' },
],
// ... other config
});
```
2. **Trigger the mutation from Lambda** using `appSyncClient` from `@ttoss/aws-appsync-nodejs`. When no `apiKey` is provided, the client automatically signs the request with the Lambda execution role's IAM credentials via AWS Signature V4:
```typescript
appSyncClient.setConfig({
endpoint: process.env.APPSYNC_ENDPOINT!,
// No apiKey — uses the Lambda execution role's IAM credentials automatically
});
await appSyncClient.mutate(
/* GraphQL */ `
mutation PublishFarmNotification($farmId: ID!, $message: String!) {
publishFarmNotification(farmId: $farmId, message: $message) {
farmId
message
}
}
`,
{ farmId: 'farm-1', message: 'Sensor alert: temperature above threshold' }
);
```
3. **Grant the Lambda execution role `appsync:GraphQL` permission** in IAM:
```json
{
"Effect": "Allow",
"Action": ["appsync:GraphQL"],
"Resource": "arn:aws:appsync:::apis//*"
}
```
> If you provide explicit credentials (e.g. from a cross-account role), pass them as `credentials: { accessKeyId, secretAccessKey, sessionToken }` to `setConfig`. See the [`@ttoss/aws-appsync-nodejs` documentation](/docs/modules/packages/aws-appsync-nodejs/) for details.
---
## Type Alias: AppSyncInfo
> **AppSyncInfo** = `object`
Defined in: [appSyncMiddleware.ts:13](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/appSyncMiddleware.ts#L13)
The shape of the `info` object passed to AppSync resolvers at runtime.
This differs from the standard `GraphQLResolveInfo` used by `graphql-middleware`.
AppSync provides a flat `parentTypeName: string` field instead of the nested
`parentType: { name: string }` object found in standard GraphQL execution.
## See
https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference.html
## Properties
### fieldName
> **fieldName**: `string`
Defined in: [appSyncMiddleware.ts:15](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/appSyncMiddleware.ts#L15)
The name of the field that is currently being resolved.
***
### parentTypeName
> **parentTypeName**: `string`
Defined in: [appSyncMiddleware.ts:17](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/appSyncMiddleware.ts#L17)
The name of the parent type for the field that is currently being resolved.
***
### selectionSetGraphQL
> **selectionSetGraphQL**: `string`
Defined in: [appSyncMiddleware.ts:23](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/appSyncMiddleware.ts#L23)
A string representation of the selection set, formatted as GraphQL SDL.
***
### selectionSetList
> **selectionSetList**: `string`[]
Defined in: [appSyncMiddleware.ts:21](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/appSyncMiddleware.ts#L21)
A list representation of the fields in the GraphQL selection set.
***
### variables
> **variables**: `Record`\<`string`, `unknown`\>
Defined in: [appSyncMiddleware.ts:19](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/appSyncMiddleware.ts#L19)
A map which holds all variables that are passed into the GraphQL request.
---
## Type Alias: AppSyncResolverHandler\
> **AppSyncResolverHandler**\<`TArguments`, `TResult`, `TSource`\> = `AwsAppSyncResolverHandler`\<`TArguments`, `TResult`, `TSource`\>
Defined in: [createAppSyncResolverHandler.ts:11](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/createAppSyncResolverHandler.ts#L11)
## Type Parameters
| Type Parameter | Default type |
| ------ | ------ |
| `TArguments` | - |
| `TResult` | - |
| `TSource` | `Record`\<`string`, `any`\> \| `null` |
---
## Type Alias: BaseAppSyncContext
> **BaseAppSyncContext** = `object`
Defined in: [createAppSyncResolverHandler.ts:20](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/createAppSyncResolverHandler.ts#L20)
The base context object passed to all AppSync resolvers.
## Properties
### handler
> **handler**: `Context`
Defined in: [createAppSyncResolverHandler.ts:22](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/createAppSyncResolverHandler.ts#L22)
The raw Lambda invocation context.
***
### identity
> **identity**: `AppSyncIdentity` \| `null` \| `undefined`
Defined in: [createAppSyncResolverHandler.ts:26](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/createAppSyncResolverHandler.ts#L26)
The caller's identity (Cognito, IAM, Lambda, or OIDC). Null when using API key auth.
***
### request
> **request**: `any`
Defined in: [createAppSyncResolverHandler.ts:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/createAppSyncResolverHandler.ts#L24)
The AppSync request object (includes headers).
---
## Type Alias: CreateContext
> **CreateContext** = (`baseContext`) => `Promise`\<`Record`\<`string`, `any`\>\> \| `Record`\<`string`, `any`\>
Defined in: [createAppSyncResolverHandler.ts:47](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/createAppSyncResolverHandler.ts#L47)
Optional async function called once per request to enrich the resolver
context. The returned object is shallow-merged into the base context and
made available to every resolver.
Use this for per-request setup such as resolving a `userId` from Cognito.
For authorization rules or before/after resolver logic, prefer `middlewares`.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `baseContext` | [`BaseAppSyncContext`](BaseAppSyncContext.md) |
## Returns
`Promise`\<`Record`\<`string`, `any`\>\> \| `Record`\<`string`, `any`\>
## Example
```ts
createAppSyncResolverHandler({
schemaComposer,
createContext: async ({ identity }) => ({
userId: await getUserIdFromCognitoSub(identity?.sub),
}),
});
```
---
## Variable: AWSDateTC
> `const` **AWSDateTC**: `ScalarTypeComposer`\<`any`\>
Defined in: [scalars.ts:11](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/scalars.ts#L11)
AWS AppSync scalar for date values (ISO 8601, e.g. `1970-01-01`).
---
## Variable: AWSDateTimeTC
> `const` **AWSDateTimeTC**: `ScalarTypeComposer`\<`any`\>
Defined in: [scalars.ts:7](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/scalars.ts#L7)
AWS AppSync scalar for combined date and time values (ISO 8601, e.g. `2007-04-05T14:30:28Z`).
---
## Variable: AWSEmailTC
> `const` **AWSEmailTC**: `ScalarTypeComposer`\<`any`\>
Defined in: [scalars.ts:21](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/scalars.ts#L21)
AWS AppSync scalar for email addresses (RFC 822).
---
## Variable: AWSIPAddressTC
> `const` **AWSIPAddressTC**: `ScalarTypeComposer`\<`any`\>
Defined in: [scalars.ts:30](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/scalars.ts#L30)
AWS AppSync scalar for IPv4 and IPv6 addresses.
---
## Variable: AWSJSONTC
> `const` **AWSJSONTC**: `ScalarTypeComposer`\<`any`\>
Defined in: [scalars.ts:4](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/scalars.ts#L4)
AWS AppSync scalar for JSON data. Represents a JSON object or array.
---
## Variable: AWSPhoneTC
> `const` **AWSPhoneTC**: `ScalarTypeComposer`\<`any`\>
Defined in: [scalars.ts:27](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/scalars.ts#L27)
AWS AppSync scalar for phone numbers (E.164 format).
---
## Variable: AWSTimeTC
> `const` **AWSTimeTC**: `ScalarTypeComposer`\<`any`\>
Defined in: [scalars.ts:14](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/scalars.ts#L14)
AWS AppSync scalar for time values (ISO 8601, e.g. `12:30:00.000Z`).
---
## Variable: AWSTimestampTC
> `const` **AWSTimestampTC**: `ScalarTypeComposer`\<`any`\>
Defined in: [scalars.ts:17](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/scalars.ts#L17)
AWS AppSync scalar for Unix epoch timestamps (integer, seconds since 1970-01-01T00:00:00Z).
---
## Variable: AWSURLTC
> `const` **AWSURLTC**: `ScalarTypeComposer`\<`any`\>
Defined in: [scalars.ts:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/scalars.ts#L24)
AWS AppSync scalar for URLs (RFC 1738).
---
## Variable: AppSyncNoneDataSourceLogicalId
> `const` **AppSyncNoneDataSourceLogicalId**: `"AppSyncNoneDataSource"` = `'AppSyncNoneDataSource'`
Defined in: [createApiTemplate.ts:20](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/appsync-api/src/createApiTemplate.ts#L20)
---
## AmazonCognito
---
## Function: createOidcVerifier()
> **createOidcVerifier**(`options`): (`token`) => `Promise`\<`JWTPayload`\>
Defined in: [Oidc/verifier.ts:51](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/Oidc/verifier.ts#L51)
Builds a token verifier for any standards-compliant OIDC provider (Entra
ID, Okta, Auth0, Google, …) with no manual JWKS wiring: the provider's
signing keys are discovered from its `/.well-known/openid-configuration`
document and cached, key rotation is handled transparently, and the
token's signature, issuer, and expiry are verified before the payload is
returned.
The returned function matches the `verifyToken` shape expected by
`McpAuthOptions` in `@ttoss/http-server-mcp` — pass it directly as
`auth.verifyToken`. Audience / resource-indicator validation is left to
the caller (e.g. `McpAuthOptions.resourceIndicator`), since the expected
audience is a property of the resource server, not the identity provider.
Discovery runs once per verifier instance — create one verifier at
startup and reuse it across requests rather than calling this per request.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `options` | [`CreateOidcVerifierOptions`](../interfaces/CreateOidcVerifierOptions.md) |
## Returns
(`token`) => `Promise`\<`JWTPayload`\>
## Example
```typescript
const verifyToken = createOidcVerifier({
issuer: 'https://login.microsoftonline.com//v2.0',
});
const mcpRouter = createMcpRouter(mcpServer, {
auth: {
verifyToken,
resourceIndicator: 'https://mcp.example.com',
},
});
```
---
## Function: discoverOidcConfiguration()
> **discoverOidcConfiguration**(`issuer`): `Promise`\<[`OidcDiscoveryDocument`](../interfaces/OidcDiscoveryDocument.md)\>
Defined in: [Oidc/discovery.ts:22](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/Oidc/discovery.ts#L22)
Fetches and parses an OpenID Connect discovery document from
`/.well-known/openid-configuration` (per the OIDC Discovery 1.0
spec, which Entra ID, Okta, and every standards-compliant OIDC provider
implement).
Throws when the endpoint is unreachable, returns a non-2xx status, or the
document is missing `jwks_uri` — there is no way to verify tokens without it.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `issuer` | `string` |
## Returns
`Promise`\<[`OidcDiscoveryDocument`](../interfaces/OidcDiscoveryDocument.md)\>
---
## Oidc
## Interfaces
- [CreateOidcVerifierOptions](interfaces/CreateOidcVerifierOptions.md)
- [OidcDiscoveryDocument](interfaces/OidcDiscoveryDocument.md)
## Functions
- [createOidcVerifier](functions/createOidcVerifier.md)
- [discoverOidcConfiguration](functions/discoverOidcConfiguration.md)
---
## Interface: CreateOidcVerifierOptions
Defined in: [Oidc/verifier.ts:6](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/Oidc/verifier.ts#L6)
Options for [createOidcVerifier](../functions/createOidcVerifier.md).
## Properties
### issuer
> **issuer**: `string`
Defined in: [Oidc/verifier.ts:14](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/Oidc/verifier.ts#L14)
The OIDC issuer URL (e.g. `https://login.microsoftonline.com//v2.0`
for Entra ID, or `https://.okta.com/oauth2/default` for Okta).
The provider's `/.well-known/openid-configuration` document is fetched
from this URL to discover its JWKS endpoint, and the token's `iss` claim
must match it exactly.
---
## Interface: OidcDiscoveryDocument
Defined in: [Oidc/discovery.ts:2](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/Oidc/discovery.ts#L2)
The subset of an OIDC discovery document this package consumes.
## Properties
### authorizationEndpoint?
> `optional` **authorizationEndpoint?**: `string`
Defined in: [Oidc/discovery.ts:8](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/Oidc/discovery.ts#L8)
Authorization endpoint, when advertised by the provider.
***
### issuer
> **issuer**: `string`
Defined in: [Oidc/discovery.ts:4](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/Oidc/discovery.ts#L4)
The issuer identifier, echoed back from the discovery document.
***
### jwksUri
> **jwksUri**: `string`
Defined in: [Oidc/discovery.ts:6](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/Oidc/discovery.ts#L6)
JWKS endpoint used to fetch the signing keys for token verification.
***
### tokenEndpoint?
> `optional` **tokenEndpoint?**: `string`
Defined in: [Oidc/discovery.ts:10](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/Oidc/discovery.ts#L10)
Token endpoint, when advertised by the provider.
---
## Class: OAuthError
Defined in: [oauth.ts:165](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L165)
Structured OAuth 2.x error with an RFC 6749 error code.
## Extends
- `Error`
## Constructors
### Constructor
> **new OAuthError**(`args`): `OAuthError`
Defined in: [oauth.ts:169](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L169)
#### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `args` | \{ `code`: `"invalid_request"` \| `"invalid_client"` \| `"invalid_grant"` \| `"unsupported_grant_type"` \| `"access_denied"` \| `"server_error"`; `description`: `string`; \} | - |
| `args.code` | `"invalid_request"` \| `"invalid_client"` \| `"invalid_grant"` \| `"unsupported_grant_type"` \| `"access_denied"` \| `"server_error"` | RFC 6749 `error` value. |
| `args.description` | `string` | Human-readable `error_description`. |
#### Returns
`OAuthError`
#### Overrides
`Error.constructor`
## Properties
### code
> `readonly` **code**: `"invalid_request"` \| `"invalid_client"` \| `"invalid_grant"` \| `"unsupported_grant_type"` \| `"access_denied"` \| `"server_error"`
Defined in: [oauth.ts:167](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L167)
RFC 6749 error code.
---
## Function: buildAuthorizationServerMetadata()
> **buildAuthorizationServerMetadata**(`args`): [`Rfc8414Metadata`](../type-aliases/Rfc8414Metadata.md)
Defined in: [oauth.ts:208](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L208)
Builds an RFC 8414 Authorization Server Metadata object.
Advertises only the `code` response type, `authorization_code` grant,
`S256` PKCE, and the `none` token endpoint auth method — matching the
MCP auth spec requirements.
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `args` | \{ `authorizationEndpoint`: `string`; `issuer`: `string`; `registrationEndpoint?`: `string`; `tokenEndpoint`: `string`; \} | - |
| `args.authorizationEndpoint` | `string` | URL of the authorization endpoint. |
| `args.issuer` | `string` | The authorization server's issuer identifier URI. |
| `args.registrationEndpoint?` | `string` | URL of the dynamic client registration endpoint (optional). |
| `args.tokenEndpoint` | `string` | URL of the token endpoint. |
## Returns
[`Rfc8414Metadata`](../type-aliases/Rfc8414Metadata.md)
---
## Function: buildProtectedResourceMetadata()
> **buildProtectedResourceMetadata**(`args`): [`Rfc9728Metadata`](../type-aliases/Rfc9728Metadata.md)
Defined in: [oauth.ts:236](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L236)
Builds an RFC 9728 Protected Resource Metadata object.
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `args` | \{ `authorizationServers`: `string`[]; `resource`: `string`; \} | - |
| `args.authorizationServers` | `string`[] | List of authorization server issuer URIs that protect this resource. |
| `args.resource` | `string` | The protected resource's identifier URI. |
## Returns
[`Rfc9728Metadata`](../type-aliases/Rfc9728Metadata.md)
---
## Function: comparePassword()
> **comparePassword**(`plainPassword`, `storedHash`): `Promise`\<`boolean`\>
Defined in: [hash.ts:75](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/hash.ts#L75)
Compares a password against a stored hash using a constant-time comparison.
Supports both the versioned `pbkdf2-sha256$$$`
format and the legacy `salt:hash` format (1,000 iterations).
## Parameters
| Parameter | Type |
| ------ | ------ |
| `plainPassword` | `string` |
| `storedHash` | `string` |
## Returns
`Promise`\<`boolean`\>
---
## Function: createAccessTokenVerifier()
> **createAccessTokenVerifier**(`options`): (`token`) => `Promise`\<[`VerifiedAccessToken`](../interfaces/VerifiedAccessToken.md) \| `null`\>
Defined in: [createAccessTokenVerifier.ts:61](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/createAccessTokenVerifier.ts#L61)
Builds a verifier for opaque, server-stored access tokens on top of an
[AccessTokenStore](../interfaces/AccessTokenStore.md). It hashes the presented bearer token, looks it up
by hash, and enforces:
- **No plaintext** — only the hash crosses the store boundary, so neither the
verifier nor the database ever holds a usable token.
- **Default-deny** — an unknown or expired token resolves to `null` without
revealing whether it ever existed.
- **Expiry** — a token past `expiresAt` is rejected; `expiresAt: null` (a
personal-API-key opt-in) skips the expiry check.
The verify path is read-only by default; opt into `touchLastUsed` to record
usage as a fire-and-forget write. Revocation is immediate — a token removed
from the store (via `delete`/`deleteBySubject`) fails the very next call.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `options` | [`AccessTokenVerifierOptions`](../interfaces/AccessTokenVerifierOptions.md) |
## Returns
(`token`) => `Promise`\<[`VerifiedAccessToken`](../interfaces/VerifiedAccessToken.md) \| `null`\>
## Example
```typescript
// Issue: mint opaque, persist only the hash.
const { token, tokenHash } = generateApiToken({ prefix: 'myapp' });
await store.save({ tokenHash, subject, scopes, clientId, expiresAt });
// Verify (e.g. wired into an MCP/HTTP auth layer).
const verify = createAccessTokenVerifier({ store, touchLastUsed: true });
const identity = await verify(bearerToken); // VerifiedAccessToken | null
```
---
## Function: createEmailAuthHandlers()
> **createEmailAuthHandlers**(`options`): [`EmailAuthHandlers`](../type-aliases/EmailAuthHandlers.md)
Defined in: [emailAuth.ts:42](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuth.ts#L42)
Runner-agnostic engine for the email and password credential flows —
password sign-up and sign-in, magic links, mailed numeric codes, address
confirmation and password reset.
It owns the security mechanics and nothing else: persistence arrives as
stores, session minting as `issueSession`, and mail delivery as `sendEmail`,
so the package carries no database and no mail-transport dependency. Mount it
with an adapter — `emailAuth()` from `@ttoss/http-server-auth` for Koa.
`modes` decides which handlers exist, so an application that only signs users
in with a mailed code never exposes a password endpoint. A configuration that
cannot be served safely throws here, at startup, rather than on a request.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `options` | [`EmailAuthOptions`](../type-aliases/EmailAuthOptions.md) |
## Returns
[`EmailAuthHandlers`](../type-aliases/EmailAuthHandlers.md)
## Example
```typescript
const handlers = createEmailAuthHandlers({
modes: ['emailCode'],
userStore,
oneTimeTokenStore,
issueSession: (user) => issueSession(user),
sendEmail: async ({ to, token }) => ses.send(buildCodeEmail(to, token)),
});
```
---
## Function: createMemoryAccessTokenStore()
> **createMemoryAccessTokenStore**(): [`AccessTokenStore`](../interfaces/AccessTokenStore.md)
Defined in: [memoryStores.ts:94](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/memoryStores.ts#L94)
In-memory reference [AccessTokenStore](../interfaces/AccessTokenStore.md). Backed by a `Map` keyed by the
token hash, with subject-scoped revocation. For tests and local development
only — production should persist tokens durably behind the same interface.
## Returns
[`AccessTokenStore`](../interfaces/AccessTokenStore.md)
---
## Function: createMemoryAuthCodeStore()
> **createMemoryAuthCodeStore**(): [`AuthCodeStore`](../interfaces/AuthCodeStore.md)
Defined in: [memoryStores.ts:47](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/memoryStores.ts#L47)
In-memory reference [AuthCodeStore](../interfaces/AuthCodeStore.md). Backed by a `Map` keyed by the
authorization code; codes are removed on exchange (single use). For tests and
local development only.
## Returns
[`AuthCodeStore`](../interfaces/AuthCodeStore.md)
---
## Function: createMemoryClientStore()
> **createMemoryClientStore**(`initial?`): [`ClientStore`](../interfaces/ClientStore.md)
Defined in: [memoryStores.ts:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/memoryStores.ts#L24)
In-memory reference [ClientStore](../interfaces/ClientStore.md). Backed by a `Map`, so state is lost
on restart — intended for tests, local development, and examples, not
production. Seed it with pre-registered clients via `initial`.
## Parameters
| Parameter | Type | Default value |
| ------ | ------ | ------ |
| `initial` | [`OAuthClient`](../interfaces/OAuthClient.md)[] | `[]` |
## Returns
[`ClientStore`](../interfaces/ClientStore.md)
---
## Function: createMemoryOneTimeTokenStore()
> **createMemoryOneTimeTokenStore**(): [`OneTimeTokenStore`](../type-aliases/OneTimeTokenStore.md)
Defined in: [memoryStores.ts:191](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/memoryStores.ts#L191)
In-memory reference [OneTimeTokenStore](../type-aliases/OneTimeTokenStore.md), keyed by `tokenHash` and
purpose. Implements the full surface, including the attempt counting the
`emailCode` mode requires. For tests and local development only.
## Returns
[`OneTimeTokenStore`](../type-aliases/OneTimeTokenStore.md)
---
## Function: createMemoryRefreshTokenStore()
> **createMemoryRefreshTokenStore**(): [`RefreshTokenStore`](../interfaces/RefreshTokenStore.md)
Defined in: [memoryStores.ts:67](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/memoryStores.ts#L67)
In-memory reference [RefreshTokenStore](../interfaces/RefreshTokenStore.md). Backed by a `Map` keyed by the
token hash, with owner-scoped revocation for reuse detection. For tests and
local development only — production should persist tokens durably.
## Returns
[`RefreshTokenStore`](../interfaces/RefreshTokenStore.md)
---
## Function: createMemoryRequestRateLimitStore()
> **createMemoryRequestRateLimitStore**(): [`RequestRateLimitStore`](../type-aliases/RequestRateLimitStore.md)
Defined in: [memoryStores.ts:244](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/memoryStores.ts#L244)
In-memory reference [RequestRateLimitStore](../type-aliases/RequestRateLimitStore.md), keyed by address and
purpose. Records are pruned on read, so the map does not grow without bound.
For tests and local development. A production deployment wants this shared
across instances — a table with an index on `(email, purpose, requested_at)`,
or a Redis counter — because a per-process limiter caps each replica
separately and so lets the fleet send N times the intended rate.
## Returns
[`RequestRateLimitStore`](../type-aliases/RequestRateLimitStore.md)
---
## Function: createMemoryUserStore()
> **createMemoryUserStore**(`initial?`): [`EmailAuthUserStore`](../type-aliases/EmailAuthUserStore.md)
Defined in: [memoryStores.ts:132](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/memoryStores.ts#L132)
In-memory reference [EmailAuthUserStore](../type-aliases/EmailAuthUserStore.md), keyed by normalized email.
Ids are sequential, so they are stable within a run but meaningless across
runs. For tests, local development, and examples only.
## Parameters
| Parameter | Type | Default value |
| ------ | ------ | ------ |
| `initial` | [`EmailAuthUser`](../type-aliases/EmailAuthUser.md)[] | `[]` |
## Returns
[`EmailAuthUserStore`](../type-aliases/EmailAuthUserStore.md)
---
## Function: createOAuthHandlers()
> **createOAuthHandlers**(`options`): [`OAuthHandlers`](../interfaces/OAuthHandlers.md)
Defined in: [oauthServer.ts:393](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServer.ts#L393)
Creates runner-agnostic OAuth 2.1 Authorization Server handlers.
Implements the authorization endpoint (PKCE S256 required), token endpoint
(`authorization_code` + `refresh_token` grants), Dynamic Client Registration
(RFC 7591), and discovery metadata (RFC 8414, plus RFC 9728 when `resource`
is set). The handlers operate on plain [OAuthRequest](../interfaces/OAuthRequest.md) /
[OAuthResponse](../interfaces/OAuthResponse.md) objects, so any HTTP runtime can host them through a
thin adapter — `@ttoss/http-server` provides the Koa one.
The app owns its user model, signing keys, and login/consent UI through the
option hooks; this core never sees them.
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`OAuthServerOptions`](../interfaces/OAuthServerOptions.md) | Authorization server configuration and pluggable hooks. |
## Returns
[`OAuthHandlers`](../interfaces/OAuthHandlers.md)
## Example
```typescript
const oauth = createOAuthHandlers({ issuer, clientStore, authCodeStore, issueTokens, onAuthorize });
const res = await oauth.token({ query: {}, body, headers });
```
---
## Function: createPostgresConsentStore()
> **createPostgresConsentStore**(`__namedParameters`): [`ConsentGrantStore`](../type-aliases/ConsentGrantStore.md)
Defined in: [postgresConsentStore.ts:55](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/postgresConsentStore.ts#L55)
Creates a [ConsentGrantStore](../type-aliases/ConsentGrantStore.md) backed by a Postgres table.
Expected table schema:
```sql
CREATE TABLE oauth_consent_grants (
code_challenge TEXT PRIMARY KEY,
subject TEXT NOT NULL,
scopes TEXT NOT NULL,
expires_at TIMESTAMPTZ NOT NULL
);
```
The `query` parameter is injected so the caller can use any runner
(`pg` Pool, `@ttoss/lambda-postgres-query`, etc.).
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | [`CreatePostgresConsentStoreOptions`](../type-aliases/CreatePostgresConsentStoreOptions.md) |
## Returns
[`ConsentGrantStore`](../type-aliases/ConsentGrantStore.md)
---
## Function: createRedirectConsentOnAuthorize()
> **createRedirectConsentOnAuthorize**(`__namedParameters`): (`args`) => `Promise`\<[`OnAuthorizeResult`](../type-aliases/OnAuthorizeResult.md)\>
Defined in: [redirectConsentOnAuthorize.ts:105](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/redirectConsentOnAuthorize.ts#L105)
Factory that produces the `onAuthorize` hook for an OAuth server with a
deferred/external consent screen.
Flow:
1. If a valid (non-expired) consent grant exists for `request.codeChallenge`,
it is consumed (deleted, single-use) and `{ approved: true }` is returned.
2. Otherwise the user is redirected to `consentUrl` with the full OAuth
request parameters so the consent screen can record its approval and
restart the authorization flow.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | [`CreateRedirectConsentOnAuthorizeOptions`](../type-aliases/CreateRedirectConsentOnAuthorizeOptions.md) |
## Returns
(`args`) => `Promise`\<[`OnAuthorizeResult`](../type-aliases/OnAuthorizeResult.md)\>
---
## Function: createRefreshRotation()
> **createRefreshRotation**(`options`): [`RefreshRotation`](../interfaces/RefreshRotation.md)
Defined in: [refreshTokenRotation.ts:113](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/refreshTokenRotation.ts#L113)
Builds a backend-agnostic refresh-token rotation engine on top of a
[RefreshTokenStore](../interfaces/RefreshTokenStore.md). It implements the OAuth 2.1 rotation mechanics that
are easy to get wrong by hand:
- **Single use** — a refresh token is consumed (marked rotated) the first
time it is exchanged; a new one is minted by your `issueTokens` hook.
- **Reuse detection** — presenting an already-consumed token signals theft or
replay, so the owner's *entire* token set is revoked, forcing re-auth.
- **Expiry** — tokens past their TTL are rejected and swept on access.
- **Scope narrowing** — a refresh request may request a subset of the granted
scopes; requesting a superset is rejected.
The "owner" of a token is the `(clientId, subject)` pair, which is the unit
revoked on reuse. Plaintext tokens are never persisted — only their hash.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `options` | [`RefreshRotationOptions`](../interfaces/RefreshRotationOptions.md) |
## Returns
[`RefreshRotation`](../interfaces/RefreshRotation.md)
## Example
```typescript
const refresh = createRefreshRotation({ store });
createOAuthHandlers({
// …,
issueTokens: async ({ subject, scopes, client }) => ({
accessToken: signJwt({ sub: subject, scope: scopes.join(' ') }),
refreshToken: await refresh.issue({ client, subject, scopes }),
expiresIn: 3600,
}),
onRefreshToken: refresh.onRefreshToken,
});
```
---
## Function: decode()
> **decode**(`encoded`): `any`
Defined in: [encodeDecode.ts:5](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/encodeDecode.ts#L5)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `encoded` | `string` |
## Returns
`any`
---
## Function: decryptValue()
> **decryptValue**(`args`): `string`
Defined in: [encryption.ts:59](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/encryption.ts#L59)
Decrypts a value produced by `encryptValue`. Throws when the key is wrong
or the ciphertext was tampered with (GCM authentication failure).
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `args` | \{ `ciphertext`: `string`; `key`: `string`; \} | - |
| `args.ciphertext` | `string` | - |
| `args.key` | `string` | 32-byte key, hex encoded (64 characters). See `generateEncryptionKey`. |
## Returns
`string`
---
## Function: encode()
> **encode**(`obj`): `string`
Defined in: [encodeDecode.ts:1](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/encodeDecode.ts#L1)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `obj` | `unknown` |
## Returns
`string`
---
## Function: encryptValue()
> **encryptValue**(`args`): `string`
Defined in: [encryption.ts:35](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/encryption.ts#L35)
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `args` | \{ `key`: `string`; `plaintext`: `string`; \} | - |
| `args.key` | `string` | 32-byte key, hex encoded (64 characters). See `generateEncryptionKey`. |
| `args.plaintext` | `string` | - |
## Returns
`string`
---
## Function: generateApiToken()
> **generateApiToken**(`args`): [`GeneratedApiToken`](../type-aliases/GeneratedApiToken.md)
Defined in: [apiToken.ts:31](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/apiToken.ts#L31)
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `args` | \{ `bytes?`: `number`; `displayPrefixLength?`: `number`; `prefix`: `string`; \} | - |
| `args.bytes?` | `number` | Number of random bytes. Defaults to 32 (64 hex characters). |
| `args.displayPrefixLength?` | `number` | Number of characters of the token kept as `displayPrefix`. Defaults to 12. |
| `args.prefix` | `string` | Application prefix, e.g. `myapp` produces tokens like `myapp_`. |
## Returns
[`GeneratedApiToken`](../type-aliases/GeneratedApiToken.md)
---
## Function: generateAuthorizationCode()
> **generateAuthorizationCode**(): [`GeneratedAuthorizationCode`](../type-aliases/GeneratedAuthorizationCode.md)
Defined in: [oauth.ts:59](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L59)
Generates a cryptographically random authorization code.
Returns the raw code (for the redirect) and its SHA-256 hash (to persist).
Mirrors the `generateOneTimeToken` / `generateApiToken` pattern.
## Returns
[`GeneratedAuthorizationCode`](../type-aliases/GeneratedAuthorizationCode.md)
---
## Function: generateEncryptionKey()
> **generateEncryptionKey**(): `string`
Defined in: [encryption.ts:21](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/encryption.ts#L21)
Generates a random 32-byte encryption key, hex encoded (64 characters).
Store it in a secret manager or environment variable.
## Returns
`string`
---
## Function: generateOneTimeToken()
> **generateOneTimeToken**(`args?`): [`OneTimeToken`](../type-aliases/OneTimeToken.md)
Defined in: [oneTimeToken.ts:118](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oneTimeToken.ts#L118)
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `args?` | \{ `bytes?`: `number`; `digits?`: `number`; `expiresInSeconds?`: `number`; `format?`: [`OneTimeTokenFormat`](../type-aliases/OneTimeTokenFormat.md); \} | - |
| `args.bytes?` | `number` | Number of random bytes. The token is the hex encoding, so the string length is twice this value. Defaults to 32. Ignored when `format` is `numeric`. |
| `args.digits?` | `number` | Number of digits when `format` is `numeric`. Defaults to 6, and must be between [MIN\_NUMERIC\_DIGITS](../variables/MIN_NUMERIC_DIGITS.md) and [MAX\_NUMERIC\_DIGITS](../variables/MAX_NUMERIC_DIGITS.md). Ignored when `format` is `hex`. |
| `args.expiresInSeconds?` | `number` | Token lifetime in seconds. Defaults to 24 hours for `hex` and 10 minutes for `numeric`, whose smaller keyspace makes a long window a guessing window. |
| `args.format?` | [`OneTimeTokenFormat`](../type-aliases/OneTimeTokenFormat.md) | Token encoding. Defaults to `hex`. |
## Returns
[`OneTimeToken`](../type-aliases/OneTimeToken.md)
---
## Function: generateWebhookSecret()
> **generateWebhookSecret**(): `string`
Defined in: [webhookSignature.ts:18](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/webhookSignature.ts#L18)
Generates a random secret for a webhook endpoint, hex encoded.
## Returns
`string`
---
## Function: getWwwAuthenticateHeader()
> **getWwwAuthenticateHeader**(`args`): `string`
Defined in: [oauthServer.ts:485](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServer.ts#L485)
Returns the `WWW-Authenticate` header value for a 401 response on a protected
resource, advertising the RFC 9728 resource-metadata URL so OAuth/MCP clients
can bootstrap discovery.
The URL comes from [protectedResourceMetadataUrl](protectedResourceMetadataUrl.md), which applies
RFC 9728 §3.1's derivation — the well-known segment goes **between** the
host and the resource's path. A resource with no path is unaffected; one
with a path previously produced `/.well-known/…`, a location the
spec does not define and no server here serves.
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `args` | \{ `resource`: `string`; \} | - |
| `args.resource` | `string` | The resource identifier. The metadata URL is derived from it per RFC 9728 §3.1. |
## Returns
`string`
## Example
```typescript
getWwwAuthenticateHeader({ resource: 'https://mcp.example.com' });
// => 'Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource"'
getWwwAuthenticateHeader({ resource: 'https://mcp.example.com/mcp' });
// => 'Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp"'
```
---
## Function: hashApiToken()
> **hashApiToken**(`token`): `string`
Defined in: [apiToken.ts:27](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/apiToken.ts#L27)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `token` | `string` |
## Returns
`string`
---
## Function: hashAuthorizationCode()
> **hashAuthorizationCode**(`args`): `string`
Defined in: [oauth.ts:49](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L49)
Hashes a raw authorization code with SHA-256 (hex output).
Use this at consumption time to look up the stored record by hash.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | \{ `code`: `string`; \} |
| `args.code` | `string` |
## Returns
`string`
---
## Function: hashClientSecret()
> **hashClientSecret**(`args`): `string`
Defined in: [oauth.ts:96](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L96)
Hashes a `client_secret` with SHA-256 (hex output).
Plain SHA-256 is the right primitive here, not `hashPassword`'s PBKDF2: a
secret issued by `handleRegister` is 32 random bytes, so there is no
low-entropy guess space for a key-derivation function to slow down.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | \{ `clientSecret`: `string`; \} |
| `args.clientSecret` | `string` |
## Returns
`string`
---
## Function: hashOneTimeToken()
> **hashOneTimeToken**(`token`): `string`
Defined in: [oneTimeToken.ts:65](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oneTimeToken.ts#L65)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `token` | `string` |
## Returns
`string`
---
## Function: hashPassword()
> **hashPassword**(`plainPassword`, `options?`): `Promise`\<`string`\>
Defined in: [hash.ts:59](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/hash.ts#L59)
Hashes a password with PBKDF2-HMAC-SHA256.
The returned string is self-describing —
`pbkdf2-sha256$$$` — so the iteration count can be
raised in the future without invalidating stored hashes.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `plainPassword` | `string` |
| `options?` | \{ `iterations?`: `number`; \} |
| `options.iterations?` | `number` |
## Returns
`Promise`\<`string`\>
---
## Function: needsRehash()
> **needsRehash**(`storedHash`): `boolean`
Defined in: [hash.ts:102](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/hash.ts#L102)
Returns true if the stored hash uses the legacy format or fewer iterations
than currently recommended. Callers can re-hash the password on the user's
next successful login.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `storedHash` | `string` |
## Returns
`boolean`
---
## Function: normalizeEmail()
> **normalizeEmail**(`email`): `string`
Defined in: [emailAuthRuntime.ts:107](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthRuntime.ts#L107)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `email` | `string` |
## Returns
`string`
---
## Function: protectedResourceMetadataDocument()
> **protectedResourceMetadataDocument**(`args`): [`ProtectedResourceMetadata`](../interfaces/ProtectedResourceMetadata.md)
Defined in: [protectedResourceMetadata.ts:56](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/protectedResourceMetadata.ts#L56)
Builds the metadata document for a resource.
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `args` | \{ `authorizationServers`: `string`[]; `resource`: `string`; \} | - |
| `args.authorizationServers` | `string`[] | Issuer identifiers of the authorization servers that issue for it. |
| `args.resource` | `string` | The resource identifier (RFC 8707) this server identifies as. |
## Returns
[`ProtectedResourceMetadata`](../interfaces/ProtectedResourceMetadata.md)
## Example
```typescript
protectedResourceMetadataDocument({
resource: 'https://mcp.example.com/mcp',
authorizationServers: ['https://auth.example.com'],
});
// => { resource: 'https://mcp.example.com/mcp',
// authorization_servers: ['https://auth.example.com'] }
```
---
## Function: protectedResourceMetadataPaths()
> **protectedResourceMetadataPaths**(`args`): `string`[]
Defined in: [protectedResourceMetadata.ts:94](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/protectedResourceMetadata.ts#L94)
Every request path the document must be served at for a given resource, most
specific first.
RFC 9728 §3.1 derives the metadata URL by inserting the well-known segment
**between the host and the path** of the resource identifier — so
`https://host/mcp` is discovered at
`https://host/.well-known/oauth-protected-resource/mcp`, *not* at
`https://host/mcp/.well-known/…` and *not* only at the root. Serving only the
root makes a client that applies the derivation rule fail discovery outright.
The root is returned as well, because clients that follow the
`resource_metadata` value in `WWW-Authenticate` (rather than deriving) have
historically been pointed there — and a resource with no path derives the
root anyway, which is why the list is de-duplicated.
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `args` | \{ `resource`: `string`; \} | - |
| `args.resource` | `string` | The resource identifier the document describes. |
## Returns
`string`[]
## Example
```typescript
protectedResourceMetadataPaths({ resource: 'https://host/mcp' });
// => ['/.well-known/oauth-protected-resource/mcp',
// '/.well-known/oauth-protected-resource']
protectedResourceMetadataPaths({ resource: 'https://host' });
// => ['/.well-known/oauth-protected-resource']
```
---
## Function: protectedResourceMetadataUrl()
> **protectedResourceMetadataUrl**(`args`): `string`
Defined in: [protectedResourceMetadata.ts:129](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/protectedResourceMetadata.ts#L129)
The absolute URL a spec-following client derives for a resource — the first
entry of [protectedResourceMetadataPaths](protectedResourceMetadataPaths.md), resolved against the
resource's own origin. This is the value to advertise in
`WWW-Authenticate: Bearer resource_metadata="…"`.
**Throws** when `resource` is not an absolute URL, unlike
[protectedResourceMetadataPaths](protectedResourceMetadataPaths.md), which falls back to the root. The
asymmetry is deliberate: a path is matched against incoming requests, so
tolerating a bad value costs a wrong route at worst and must not crash route
registration — whereas this value is *handed to clients* in a response
header, where an unparseable URL is a dead end the client cannot work around
and nobody operating the server would see. Fail at wiring time instead.
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `args` | \{ `resource`: `string`; \} | - |
| `args.resource` | `string` | The resource identifier the document describes. Must be an absolute URL. |
## Returns
`string`
## Throws
when `resource` is not an absolute URL.
## Example
```typescript
protectedResourceMetadataUrl({ resource: 'https://host/mcp' });
// => 'https://host/.well-known/oauth-protected-resource/mcp'
```
---
## Function: signJwt()
> **signJwt**(`args`): `string`
Defined in: [jwt.ts:47](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/jwt.ts#L47)
Signs a JWT with HMAC-SHA256 (HS256).
For Amazon Cognito tokens, use `@ttoss/auth-core/amazon-cognito` instead —
this helper is meant for self-hosted authentication where the application
owns the signing secret.
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `args` | \{ `expiresInSeconds?`: `number`; `payload`: [`JwtPayload`](../type-aliases/JwtPayload.md); `secret`: `string`; \} | - |
| `args.expiresInSeconds?` | `number` | Token lifetime in seconds, e.g. `60 * 60 * 24 * 7` for 7 days. When omitted, the token never expires. |
| `args.payload` | [`JwtPayload`](../type-aliases/JwtPayload.md) | - |
| `args.secret` | `string` | - |
## Returns
`string`
---
## Function: signWebhookPayload()
> **signWebhookPayload**(`args`): `string`
Defined in: [webhookSignature.ts:26](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/webhookSignature.ts#L26)
Signs a serialized payload, returning a `sha256=` signature to send
in a header alongside the request.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | \{ `payload`: `string`; `secret`: `string`; \} |
| `args.payload` | `string` |
| `args.secret` | `string` |
## Returns
`string`
---
## Function: validateRedirectUri()
> **validateRedirectUri**(`args`): `boolean`
Defined in: [oauth.ts:140](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L140)
Returns `true` only if `redirectUri` exactly matches one of
`allowedRedirectUris`.
Intentionally uses strict string equality: no trailing-slash
normalization, no query-string stripping, no host suffix checks.
This function is pure (no `node:crypto`) so it can be bundled for
browser-side consent pages.
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `args` | \{ `allowedRedirectUris`: readonly `string`[]; `redirectUri`: `string`; \} | - |
| `args.allowedRedirectUris` | readonly `string`[] | Exact URIs registered for the client. |
| `args.redirectUri` | `string` | The `redirect_uri` from the authorization request. |
## Returns
`boolean`
---
## Function: verifyApiToken()
> **verifyApiToken**(`args`): `boolean`
Defined in: [apiToken.ts:62](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/apiToken.ts#L62)
Constant-time check of a plain token against a stored hash, optionally
validating expiration.
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `args` | \{ `expiresAt?`: `Date` \| `null`; `token`: `string`; `tokenHash`: `string`; \} | - |
| `args.expiresAt?` | `Date` \| `null` | When provided, the token is rejected after this date. Omit (or pass `null`) for tokens that never expire. |
| `args.token` | `string` | - |
| `args.tokenHash` | `string` | - |
## Returns
`boolean`
---
## Function: verifyClientSecret()
> **verifyClientSecret**(`args`): `boolean`
Defined in: [oauth.ts:107](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L107)
Verifies a presented `client_secret` against a stored SHA-256 hash in
constant time.
Returns `false` for an absent or empty presented secret, so a confidential
client can never authenticate by omitting the credential.
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `args` | \{ `clientSecret`: `string` \| `undefined`; `clientSecretHash`: `string`; \} | - |
| `args.clientSecret` | `string` \| `undefined` | The secret presented at the token endpoint. |
| `args.clientSecretHash` | `string` | The stored SHA-256 hex hash to compare against. |
## Returns
`boolean`
---
## Function: verifyJwt()
> **verifyJwt**(`args`): [`JwtPayload`](../type-aliases/JwtPayload.md) \| `null`
Defined in: [jwt.ts:79](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/jwt.ts#L79)
Verifies an HS256 JWT signature and expiration.
Returns the payload when the token is valid, or `null` when the token is
malformed, has an invalid signature, or is expired.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | \{ `secret`: `string`; `token`: `string`; \} |
| `args.secret` | `string` |
| `args.token` | `string` |
## Returns
[`JwtPayload`](../type-aliases/JwtPayload.md) \| `null`
---
## Function: verifyOneTimeToken()
> **verifyOneTimeToken**(`args`): `boolean`
Defined in: [oneTimeToken.ts:166](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oneTimeToken.ts#L166)
Constant-time check of a plain token against a stored hash, also validating
the expiration date.
This is a single-guess check and deliberately keeps no state, so a `numeric`
token needs the caller to bound how many guesses a stored record accepts —
`createEmailAuthHandlers` does that through
`OneTimeTokenStore.incrementAttempts`.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | \{ `expires`: `Date`; `token`: `string`; `tokenHash`: `string`; \} |
| `args.expires` | `Date` |
| `args.token` | `string` |
| `args.tokenHash` | `string` |
## Returns
`boolean`
---
## Function: verifyPkceChallenge()
> **verifyPkceChallenge**(`args`): `boolean`
Defined in: [oauth.ts:13](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L13)
Verifies a PKCE code challenge against a code verifier.
Only the `S256` method is accepted. Passing `plain` or any other method
always returns `false`.
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `args` | \{ `codeChallenge`: `string`; `codeChallengeMethod`: `string`; `codeVerifier`: `string`; \} | - |
| `args.codeChallenge` | `string` | The `code_challenge` value the client sent in the authorization request. |
| `args.codeChallengeMethod` | `string` | The `code_challenge_method` advertised by the client. Must be `S256`. |
| `args.codeVerifier` | `string` | The original `code_verifier` string from the client. |
## Returns
`boolean`
---
## Function: verifyWebhookSignature()
> **verifyWebhookSignature**(`args`): `boolean`
Defined in: [webhookSignature.ts:41](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/webhookSignature.ts#L41)
Constant-time verification of a received webhook signature. Accepts the
signature with or without the `sha256=` prefix.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | \{ `payload`: `string`; `secret`: `string`; `signature`: `string`; \} |
| `args.payload` | `string` |
| `args.secret` | `string` |
| `args.signature` | `string` |
## Returns
`boolean`
---
## index
## Classes
- [OAuthError](classes/OAuthError.md)
## Interfaces
- [AccessTokenStore](interfaces/AccessTokenStore.md)
- [AccessTokenVerifierOptions](interfaces/AccessTokenVerifierOptions.md)
- [AuthCodeStore](interfaces/AuthCodeStore.md)
- [AuthorizeRequest](interfaces/AuthorizeRequest.md)
- [ClientStore](interfaces/ClientStore.md)
- [IssuedTokens](interfaces/IssuedTokens.md)
- [IssueRefreshTokenArgs](interfaces/IssueRefreshTokenArgs.md)
- [IssueTokensArgs](interfaces/IssueTokensArgs.md)
- [OAuthClient](interfaces/OAuthClient.md)
- [OAuthClientMetadata](interfaces/OAuthClientMetadata.md)
- [OAuthHandlers](interfaces/OAuthHandlers.md)
- [OAuthRequest](interfaces/OAuthRequest.md)
- [OAuthResponse](interfaces/OAuthResponse.md)
- [OAuthServerOptions](interfaces/OAuthServerOptions.md)
- [OnAuthorizeArgs](interfaces/OnAuthorizeArgs.md)
- [OnRefreshTokenArgs](interfaces/OnRefreshTokenArgs.md)
- [ProtectedResourceMetadata](interfaces/ProtectedResourceMetadata.md)
- [RefreshRotation](interfaces/RefreshRotation.md)
- [RefreshRotationOptions](interfaces/RefreshRotationOptions.md)
- [RefreshTokenStore](interfaces/RefreshTokenStore.md)
- [StoredAccessToken](interfaces/StoredAccessToken.md)
- [StoredAuthorizationCode](interfaces/StoredAuthorizationCode.md)
- [StoredRefreshToken](interfaces/StoredRefreshToken.md)
- [VerifiedAccessToken](interfaces/VerifiedAccessToken.md)
## Type Aliases
- [AuthHttpRequest](type-aliases/AuthHttpRequest.md)
- [AuthHttpResponse](type-aliases/AuthHttpResponse.md)
- [ClientDisplay](type-aliases/ClientDisplay.md)
- [ConsentGrant](type-aliases/ConsentGrant.md)
- [ConsentGrantStore](type-aliases/ConsentGrantStore.md)
- [ConsentStoreQuery](type-aliases/ConsentStoreQuery.md)
- [CreatePostgresConsentStoreOptions](type-aliases/CreatePostgresConsentStoreOptions.md)
- [CreateRedirectConsentOnAuthorizeOptions](type-aliases/CreateRedirectConsentOnAuthorizeOptions.md)
- [EmailAuthDelivery](type-aliases/EmailAuthDelivery.md)
- [EmailAuthErrorCode](type-aliases/EmailAuthErrorCode.md)
- [EmailAuthHandler](type-aliases/EmailAuthHandler.md)
- [EmailAuthHandlers](type-aliases/EmailAuthHandlers.md)
- [EmailAuthHooks](type-aliases/EmailAuthHooks.md)
- [EmailAuthMode](type-aliases/EmailAuthMode.md)
- [EmailAuthOptions](type-aliases/EmailAuthOptions.md)
- [EmailAuthPaths](type-aliases/EmailAuthPaths.md)
- [EmailAuthSession](type-aliases/EmailAuthSession.md)
- [EmailAuthTtl](type-aliases/EmailAuthTtl.md)
- [EmailAuthUser](type-aliases/EmailAuthUser.md)
- [EmailAuthUserStore](type-aliases/EmailAuthUserStore.md)
- [EmailCodeOptions](type-aliases/EmailCodeOptions.md)
- [GeneratedApiToken](type-aliases/GeneratedApiToken.md)
- [GeneratedAuthorizationCode](type-aliases/GeneratedAuthorizationCode.md)
- [JwtPayload](type-aliases/JwtPayload.md)
- [OAuthErrorCode](type-aliases/OAuthErrorCode.md)
- [OnAuthorizeResult](type-aliases/OnAuthorizeResult.md)
- [OneTimeToken](type-aliases/OneTimeToken.md)
- [OneTimeTokenFormat](type-aliases/OneTimeTokenFormat.md)
- [OneTimeTokenPurpose](type-aliases/OneTimeTokenPurpose.md)
- [OneTimeTokenStore](type-aliases/OneTimeTokenStore.md)
- [OnRefreshTokenResult](type-aliases/OnRefreshTokenResult.md)
- [PasswordOptions](type-aliases/PasswordOptions.md)
- [RequestRateLimit](type-aliases/RequestRateLimit.md)
- [RequestRateLimitStore](type-aliases/RequestRateLimitStore.md)
- [Rfc8414Metadata](type-aliases/Rfc8414Metadata.md)
- [Rfc9728Metadata](type-aliases/Rfc9728Metadata.md)
- [StoredOneTimeToken](type-aliases/StoredOneTimeToken.md)
## Variables
- [emailAuthErrorCodes](variables/emailAuthErrorCodes.md)
- [MAX\_NUMERIC\_DIGITS](variables/MAX_NUMERIC_DIGITS.md)
- [MIN\_NUMERIC\_DIGITS](variables/MIN_NUMERIC_DIGITS.md)
- [oauthErrorCodes](variables/oauthErrorCodes.md)
## Functions
- [buildAuthorizationServerMetadata](functions/buildAuthorizationServerMetadata.md)
- [buildProtectedResourceMetadata](functions/buildProtectedResourceMetadata.md)
- [comparePassword](functions/comparePassword.md)
- [createAccessTokenVerifier](functions/createAccessTokenVerifier.md)
- [createEmailAuthHandlers](functions/createEmailAuthHandlers.md)
- [createMemoryAccessTokenStore](functions/createMemoryAccessTokenStore.md)
- [createMemoryAuthCodeStore](functions/createMemoryAuthCodeStore.md)
- [createMemoryClientStore](functions/createMemoryClientStore.md)
- [createMemoryOneTimeTokenStore](functions/createMemoryOneTimeTokenStore.md)
- [createMemoryRefreshTokenStore](functions/createMemoryRefreshTokenStore.md)
- [createMemoryRequestRateLimitStore](functions/createMemoryRequestRateLimitStore.md)
- [createMemoryUserStore](functions/createMemoryUserStore.md)
- [createOAuthHandlers](functions/createOAuthHandlers.md)
- [createPostgresConsentStore](functions/createPostgresConsentStore.md)
- [createRedirectConsentOnAuthorize](functions/createRedirectConsentOnAuthorize.md)
- [createRefreshRotation](functions/createRefreshRotation.md)
- [decode](functions/decode.md)
- [decryptValue](functions/decryptValue.md)
- [encode](functions/encode.md)
- [encryptValue](functions/encryptValue.md)
- [generateApiToken](functions/generateApiToken.md)
- [generateAuthorizationCode](functions/generateAuthorizationCode.md)
- [generateEncryptionKey](functions/generateEncryptionKey.md)
- [generateOneTimeToken](functions/generateOneTimeToken.md)
- [generateWebhookSecret](functions/generateWebhookSecret.md)
- [getWwwAuthenticateHeader](functions/getWwwAuthenticateHeader.md)
- [hashApiToken](functions/hashApiToken.md)
- [hashAuthorizationCode](functions/hashAuthorizationCode.md)
- [hashClientSecret](functions/hashClientSecret.md)
- [hashOneTimeToken](functions/hashOneTimeToken.md)
- [hashPassword](functions/hashPassword.md)
- [needsRehash](functions/needsRehash.md)
- [normalizeEmail](functions/normalizeEmail.md)
- [protectedResourceMetadataDocument](functions/protectedResourceMetadataDocument.md)
- [protectedResourceMetadataPaths](functions/protectedResourceMetadataPaths.md)
- [protectedResourceMetadataUrl](functions/protectedResourceMetadataUrl.md)
- [signJwt](functions/signJwt.md)
- [signWebhookPayload](functions/signWebhookPayload.md)
- [validateRedirectUri](functions/validateRedirectUri.md)
- [verifyApiToken](functions/verifyApiToken.md)
- [verifyClientSecret](functions/verifyClientSecret.md)
- [verifyJwt](functions/verifyJwt.md)
- [verifyOneTimeToken](functions/verifyOneTimeToken.md)
- [verifyPkceChallenge](functions/verifyPkceChallenge.md)
- [verifyWebhookSignature](functions/verifyWebhookSignature.md)
---
## Interface: AccessTokenStore
Defined in: [oauthServerTypes.ts:249](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L249)
App-provided store for opaque access tokens, looked up by hash. The store is
pure persistence — the verification mechanics (expiry, default-deny) live in
`createAccessTokenVerifier`. Back it with DynamoDB, Postgres, in-memory, …
Storing the hash, not the token, is a contract: a store compromise yields no
usable credentials. Revocation is first-class — `delete` kills one token;
`deleteBySubject` kills every token for a user (offboarding, compromise).
## Properties
### delete
> **delete**: (`tokenHash`) => `void` \| `Promise`\<`void`\>
Defined in: [oauthServerTypes.ts:257](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L257)
Remove a single access token by its hash (revoke one session/key).
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `tokenHash` | `string` |
#### Returns
`void` \| `Promise`\<`void`\>
***
### deleteBySubject
> **deleteBySubject**: (`subject`) => `void` \| `Promise`\<`void`\>
Defined in: [oauthServerTypes.ts:262](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L262)
Remove every access token for a subject. Called to revoke all of a user's
access at once on offboarding or suspected compromise.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `subject` | `string` |
#### Returns
`void` \| `Promise`\<`void`\>
***
### get
> **get**: (`tokenHash`) => [`StoredAccessToken`](StoredAccessToken.md) \| `Promise`\<[`StoredAccessToken`](StoredAccessToken.md) \| `undefined`\> \| `undefined`
Defined in: [oauthServerTypes.ts:253](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L253)
Look up an access token by its hash. Return `undefined` if unknown.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `tokenHash` | `string` |
#### Returns
[`StoredAccessToken`](StoredAccessToken.md) \| `Promise`\<[`StoredAccessToken`](StoredAccessToken.md) \| `undefined`\> \| `undefined`
***
### listBySubject?
> `optional` **listBySubject?**: (`subject`) => [`StoredAccessToken`](StoredAccessToken.md)[] \| `Promise`\<[`StoredAccessToken`](StoredAccessToken.md)[]\>
Defined in: [oauthServerTypes.ts:277](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L277)
Return every token belonging to a subject, for "your authorized
apps / personal API keys" listing UIs. Optional; `createMemoryAccessTokenStore`
implements this.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `subject` | `string` |
#### Returns
[`StoredAccessToken`](StoredAccessToken.md)[] \| `Promise`\<[`StoredAccessToken`](StoredAccessToken.md)[]\>
***
### save
> **save**: (`token`) => `void` \| `Promise`\<`void`\>
Defined in: [oauthServerTypes.ts:251](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L251)
Persist an access token, upserting by `tokenHash`.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `token` | [`StoredAccessToken`](StoredAccessToken.md) |
#### Returns
`void` \| `Promise`\<`void`\>
***
### touchLastUsed?
> `optional` **touchLastUsed?**: (`args`) => `void` \| `Promise`\<`void`\>
Defined in: [oauthServerTypes.ts:268](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L268)
Record the time a token was last presented. Optional and fire-and-forget:
implementations MUST NOT block or fail verification on this write, and
SHOULD use a writable client (never a read-only replica).
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | \{ `lastUsedAt`: `number`; `tokenHash`: `string`; \} |
| `args.lastUsedAt` | `number` |
| `args.tokenHash` | `string` |
#### Returns
`void` \| `Promise`\<`void`\>
---
## Interface: AccessTokenVerifierOptions
Defined in: [createAccessTokenVerifier.ts:15](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/createAccessTokenVerifier.ts#L15)
Options for [createAccessTokenVerifier](../functions/createAccessTokenVerifier.md).
## Properties
### hashToken?
> `optional` **hashToken?**: (`token`) => `string`
Defined in: [createAccessTokenVerifier.ts:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/createAccessTokenVerifier.ts#L24)
Override the hashing applied to the presented token before lookup.
Defaults to SHA-256 (hex) — the same hash `generateApiToken` produces, so
tokens minted there verify with no extra wiring. The plaintext is never
stored or compared directly.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `token` | `string` |
#### Returns
`string`
***
### store
> **store**: [`AccessTokenStore`](AccessTokenStore.md)
Defined in: [createAccessTokenVerifier.ts:17](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/createAccessTokenVerifier.ts#L17)
App-provided persistence for access tokens.
***
### touchLastUsed?
> `optional` **touchLastUsed?**: `boolean`
Defined in: [createAccessTokenVerifier.ts:31](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/createAccessTokenVerifier.ts#L31)
When `true`, record `lastUsedAt` on every successful verification via
`store.touchLastUsed`. Fire-and-forget: the write never blocks the
verification result and a failure is swallowed.
#### Default
```ts
false
```
---
## Interface: AuthCodeStore
Defined in: [oauthServerTypes.ts:141](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L141)
App-provided store for authorization codes. Codes are single-use and
short-lived; the app decides where to persist them.
## Properties
### delete
> **delete**: (`code`) => `void` \| `Promise`\<`void`\>
Defined in: [oauthServerTypes.ts:152](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L152)
Remove an authorization code (called on exchange to enforce single use).
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `code` | `string` |
#### Returns
`void` \| `Promise`\<`void`\>
***
### get
> **get**: (`code`) => [`StoredAuthorizationCode`](StoredAuthorizationCode.md) \| `Promise`\<[`StoredAuthorizationCode`](StoredAuthorizationCode.md) \| `undefined`\> \| `undefined`
Defined in: [oauthServerTypes.ts:145](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L145)
Look up an authorization code by its value.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `code` | `string` |
#### Returns
[`StoredAuthorizationCode`](StoredAuthorizationCode.md) \| `Promise`\<[`StoredAuthorizationCode`](StoredAuthorizationCode.md) \| `undefined`\> \| `undefined`
***
### save
> **save**: (`code`) => `void` \| `Promise`\<`void`\>
Defined in: [oauthServerTypes.ts:143](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L143)
Persist an authorization code.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `code` | [`StoredAuthorizationCode`](StoredAuthorizationCode.md) |
#### Returns
`void` \| `Promise`\<`void`\>
---
## Interface: AuthorizeRequest
Defined in: [oauthServerTypes.ts:309](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L309)
The validated authorization request passed to the consent/login hook.
## Properties
### clientId
> **clientId**: `string`
Defined in: [oauthServerTypes.ts:311](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L311)
The requesting `client_id`.
***
### codeChallenge
> **codeChallenge**: `string`
Defined in: [oauthServerTypes.ts:319](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L319)
The PKCE `code_challenge`.
***
### codeChallengeMethod
> **codeChallengeMethod**: `string`
Defined in: [oauthServerTypes.ts:321](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L321)
The PKCE challenge method (always `'S256'`).
***
### redirectUri
> **redirectUri**: `string`
Defined in: [oauthServerTypes.ts:313](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L313)
The validated redirect URI.
***
### scopes
> **scopes**: `string`[]
Defined in: [oauthServerTypes.ts:315](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L315)
The requested scopes.
***
### state?
> `optional` **state?**: `string`
Defined in: [oauthServerTypes.ts:317](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L317)
Opaque CSRF/state value to echo back on redirect.
---
## Interface: ClientStore
Defined in: [oauthServerTypes.ts:81](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L81)
App-provided store for OAuth clients. The core owns protocol mechanics; the
app owns persistence (DynamoDB, Postgres, in-memory, …).
## Properties
### get
> **get**: (`clientId`) => [`OAuthClient`](OAuthClient.md) \| `Promise`\<[`OAuthClient`](OAuthClient.md) \| `undefined`\> \| `undefined`
Defined in: [oauthServerTypes.ts:89](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L89)
Look up a client by its `client_id`. Return `undefined` if unknown.
A store that implements [ClientStore.verifyClientSecret](#verifyclientsecret) should omit
`client_secret` from the returned document — the core never needs the raw
value, and leaving it out keeps it from reaching consent screens or logs.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `clientId` | `string` |
#### Returns
[`OAuthClient`](OAuthClient.md) \| `Promise`\<[`OAuthClient`](OAuthClient.md) \| `undefined`\> \| `undefined`
***
### register
> **register**: (`client`) => `void` \| `Promise`\<`void`\>
Defined in: [oauthServerTypes.ts:93](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L93)
Persist a newly registered client.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `client` | [`OAuthClient`](OAuthClient.md) |
#### Returns
`void` \| `Promise`\<`void`\>
***
### verifyClientSecret?
> `optional` **verifyClientSecret?**: (`args`) => `boolean` \| `Promise`\<`boolean`\>
Defined in: [oauthServerTypes.ts:108](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L108)
Verifies a `client_secret` presented at the token endpoint. Implement this
to keep secrets hashed at rest: the core hands over the presented value and
the store compares it against its own stored form, so the raw secret never
has to be recoverable.
Return `true` for a public client (one registered with
`token_endpoint_auth_method: 'none'`, which has no secret to present), and
`false` for an unknown `client_id`.
When omitted, the core falls back to a constant-time comparison against the
`client_secret` returned by [ClientStore.get](#get) — which requires the
store to keep the secret recoverable.
#### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `args` | \{ `clientId`: `string`; `clientSecret`: `string` \| `undefined`; \} | - |
| `args.clientId` | `string` | The `client_id` being authenticated. |
| `args.clientSecret` | `string` \| `undefined` | The secret presented by the client, absent when none was sent. |
#### Returns
`boolean` \| `Promise`\<`boolean`\>
---
## Interface: IssueRefreshTokenArgs
Defined in: [refreshTokenRotation.ts:58](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/refreshTokenRotation.ts#L58)
Arguments for [RefreshRotation.issue](RefreshRotation.md#issue).
## Properties
### client
> **client**: [`OAuthClient`](OAuthClient.md)
Defined in: [refreshTokenRotation.ts:60](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/refreshTokenRotation.ts#L60)
The client the token is issued to.
***
### scopes
> **scopes**: `string`[]
Defined in: [refreshTokenRotation.ts:64](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/refreshTokenRotation.ts#L64)
The scopes granted to the token.
***
### subject
> **subject**: `string`
Defined in: [refreshTokenRotation.ts:62](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/refreshTokenRotation.ts#L62)
The authenticated end-user subject identifier.
---
## Interface: IssueTokensArgs
Defined in: [oauthServerTypes.ts:299](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L299)
Arguments passed to [OAuthServerOptions.issueTokens](OAuthServerOptions.md#issuetokens).
## Properties
### client
> **client**: [`OAuthClient`](OAuthClient.md)
Defined in: [oauthServerTypes.ts:305](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L305)
The client the tokens are being issued to.
***
### scopes
> **scopes**: `string`[]
Defined in: [oauthServerTypes.ts:303](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L303)
The scopes granted to the token.
***
### subject
> **subject**: `string`
Defined in: [oauthServerTypes.ts:301](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L301)
The authenticated end-user subject identifier.
---
## Interface: IssuedTokens
Defined in: [oauthServerTypes.ts:287](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L287)
Tokens returned by the app's [OAuthServerOptions.issueTokens](OAuthServerOptions.md#issuetokens) hook.
## Properties
### accessToken
> **accessToken**: `string`
Defined in: [oauthServerTypes.ts:289](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L289)
The access token string (JWT, opaque, …).
***
### expiresIn?
> `optional` **expiresIn?**: `number`
Defined in: [oauthServerTypes.ts:293](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L293)
Access token lifetime in seconds, surfaced as `expires_in`.
***
### refreshToken?
> `optional` **refreshToken?**: `string`
Defined in: [oauthServerTypes.ts:291](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L291)
Optional refresh token enabling the `refresh_token` grant.
***
### scope?
> `optional` **scope?**: `string`
Defined in: [oauthServerTypes.ts:295](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L295)
Granted scopes as a space-separated string. Defaults to the bound scopes.
---
## Interface: OAuthClient
Defined in: [oauthServerTypes.ts:68](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L68)
A registered OAuth client as persisted by the app's [ClientStore](ClientStore.md).
## Extends
- [`OAuthClientMetadata`](OAuthClientMetadata.md)
## Indexable
> \[`key`: `string`\]: `unknown`
## Properties
### client\_id
> **client\_id**: `string`
Defined in: [oauthServerTypes.ts:70](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L70)
Unique client identifier issued by the authorization server.
***
### client\_id\_issued\_at?
> `optional` **client\_id\_issued\_at?**: `number`
Defined in: [oauthServerTypes.ts:74](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L74)
Unix timestamp (seconds) when the client was registered.
***
### client\_name?
> `optional` **client\_name?**: `string`
Defined in: [oauthServerTypes.ts:51](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L51)
Human-readable client name shown on consent screens.
#### Inherited from
[`OAuthClientMetadata`](OAuthClientMetadata.md).[`client_name`](OAuthClientMetadata.md#client_name)
***
### client\_secret?
> `optional` **client\_secret?**: `string`
Defined in: [oauthServerTypes.ts:72](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L72)
Client secret for confidential clients. Absent for public clients.
***
### grant\_types?
> `optional` **grant\_types?**: `string`[]
Defined in: [oauthServerTypes.ts:53](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L53)
OAuth grant types the client will use. Defaults to auth-code + refresh.
#### Inherited from
[`OAuthClientMetadata`](OAuthClientMetadata.md).[`grant_types`](OAuthClientMetadata.md#grant_types)
***
### redirect\_uris
> **redirect\_uris**: `string`[]
Defined in: [oauthServerTypes.ts:49](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L49)
Allowed redirect URIs. At least one is required for the auth-code flow.
#### Inherited from
[`OAuthClientMetadata`](OAuthClientMetadata.md).[`redirect_uris`](OAuthClientMetadata.md#redirect_uris)
***
### response\_types?
> `optional` **response\_types?**: `string`[]
Defined in: [oauthServerTypes.ts:55](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L55)
OAuth response types the client will use. Defaults to `['code']`.
#### Inherited from
[`OAuthClientMetadata`](OAuthClientMetadata.md).[`response_types`](OAuthClientMetadata.md#response_types)
***
### scope?
> `optional` **scope?**: `string`
Defined in: [oauthServerTypes.ts:63](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L63)
Space-separated scopes the client may request.
#### Inherited from
[`OAuthClientMetadata`](OAuthClientMetadata.md).[`scope`](OAuthClientMetadata.md#scope)
***
### token\_endpoint\_auth\_method?
> `optional` **token\_endpoint\_auth\_method?**: `string`
Defined in: [oauthServerTypes.ts:61](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L61)
Client authentication method at the token endpoint. `'none'` registers a
public client (no secret issued); anything else registers a confidential
client and a `client_secret` is generated.
#### Inherited from
[`OAuthClientMetadata`](OAuthClientMetadata.md).[`token_endpoint_auth_method`](OAuthClientMetadata.md#token_endpoint_auth_method)
---
## Interface: OAuthClientMetadata
Defined in: [oauthServerTypes.ts:47](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L47)
Client metadata as submitted to Dynamic Client Registration (RFC 7591).
## Extended by
- [`OAuthClient`](OAuthClient.md)
## Indexable
> \[`key`: `string`\]: `unknown`
## Properties
### client\_name?
> `optional` **client\_name?**: `string`
Defined in: [oauthServerTypes.ts:51](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L51)
Human-readable client name shown on consent screens.
***
### grant\_types?
> `optional` **grant\_types?**: `string`[]
Defined in: [oauthServerTypes.ts:53](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L53)
OAuth grant types the client will use. Defaults to auth-code + refresh.
***
### redirect\_uris
> **redirect\_uris**: `string`[]
Defined in: [oauthServerTypes.ts:49](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L49)
Allowed redirect URIs. At least one is required for the auth-code flow.
***
### response\_types?
> `optional` **response\_types?**: `string`[]
Defined in: [oauthServerTypes.ts:55](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L55)
OAuth response types the client will use. Defaults to `['code']`.
***
### scope?
> `optional` **scope?**: `string`
Defined in: [oauthServerTypes.ts:63](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L63)
Space-separated scopes the client may request.
***
### token\_endpoint\_auth\_method?
> `optional` **token\_endpoint\_auth\_method?**: `string`
Defined in: [oauthServerTypes.ts:61](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L61)
Client authentication method at the token endpoint. `'none'` registers a
public client (no secret issued); anything else registers a confidential
client and a `client_secret` is generated.
---
## Interface: OAuthHandlers
Defined in: [oauthServerTypes.ts:416](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L416)
The runner-agnostic OAuth server handlers returned by [createOAuthHandlers](../functions/createOAuthHandlers.md).
## Properties
### authorizationServerMetadata
> **authorizationServerMetadata**: () => [`OAuthResponse`](OAuthResponse.md)
Defined in: [oauthServerTypes.ts:420](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L420)
RFC 8414 Authorization Server Metadata response.
#### Returns
[`OAuthResponse`](OAuthResponse.md)
***
### authorize
> **authorize**: (`request`) => `Promise`\<[`OAuthResponse`](OAuthResponse.md)\>
Defined in: [oauthServerTypes.ts:424](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L424)
Handle a `GET /authorize` request.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `request` | [`OAuthRequest`](OAuthRequest.md) |
#### Returns
`Promise`\<[`OAuthResponse`](OAuthResponse.md)\>
***
### paths
> **paths**: `object`
Defined in: [oauthServerTypes.ts:418](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L418)
Resolved endpoint paths, for an adapter to mount routes on.
#### authorize
> **authorize**: `string`
#### register
> **register**: `string`
#### token
> **token**: `string`
***
### protectedResourceMetadata
> **protectedResourceMetadata**: () => [`OAuthResponse`](OAuthResponse.md) \| `undefined`
Defined in: [oauthServerTypes.ts:422](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L422)
RFC 9728 Protected Resource Metadata response, or `undefined` if `resource` is unset.
#### Returns
[`OAuthResponse`](OAuthResponse.md) \| `undefined`
***
### register
> **register**: (`request`) => `Promise`\<[`OAuthResponse`](OAuthResponse.md)\>
Defined in: [oauthServerTypes.ts:428](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L428)
Handle a `POST /register` request (Dynamic Client Registration, RFC 7591).
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `request` | [`OAuthRequest`](OAuthRequest.md) |
#### Returns
`Promise`\<[`OAuthResponse`](OAuthResponse.md)\>
***
### token
> **token**: (`request`) => `Promise`\<[`OAuthResponse`](OAuthResponse.md)\>
Defined in: [oauthServerTypes.ts:426](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L426)
Handle a `POST /token` request (authorization_code + refresh_token grants).
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `request` | [`OAuthRequest`](OAuthRequest.md) |
#### Returns
`Promise`\<[`OAuthResponse`](OAuthResponse.md)\>
---
## Interface: OAuthRequest
Defined in: [oauthServerTypes.ts:20](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L20)
A normalized inbound HTTP request, framework-agnostic.
## Properties
### body
> **body**: `Record`\<`string`, `unknown`\>
Defined in: [oauthServerTypes.ts:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L24)
Parsed request body (e.g. form-encoded `/token` or JSON `/register`).
***
### headers
> **headers**: `Record`\<`string`, `string` \| `undefined`\>
Defined in: [oauthServerTypes.ts:26](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L26)
Request headers, lower-cased keys recommended (e.g. `authorization`).
***
### query
> **query**: `Record`\<`string`, `string` \| `undefined`\>
Defined in: [oauthServerTypes.ts:22](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L22)
Query-string parameters (e.g. from `/authorize?client_id=...`).
---
## Interface: OAuthResponse
Defined in: [oauthServerTypes.ts:33](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L33)
A normalized outbound HTTP response. Either a JSON `body` with `status`, or a
`redirect` (302) — never both. Adapters apply this to their own response.
## Properties
### body?
> `optional` **body?**: `unknown`
Defined in: [oauthServerTypes.ts:37](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L37)
JSON-serializable response body.
***
### redirect?
> `optional` **redirect?**: `string`
Defined in: [oauthServerTypes.ts:39](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L39)
When set, the adapter should issue a 302 redirect to this URL.
***
### status
> **status**: `number`
Defined in: [oauthServerTypes.ts:35](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L35)
HTTP status code. Defaults to 200 when `redirect` is unset.
---
## Interface: OAuthServerOptions
Defined in: [oauthServerTypes.ts:365](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L365)
Configuration for [createOAuthHandlers](../functions/createOAuthHandlers.md).
## Properties
### authCodeStore
> **authCodeStore**: [`AuthCodeStore`](AuthCodeStore.md)
Defined in: [oauthServerTypes.ts:371](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L371)
App-provided store for short-lived authorization codes.
***
### authorizationCodeTtl?
> `optional` **authorizationCodeTtl?**: `number`
Defined in: [oauthServerTypes.ts:403](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L403)
Authorization code lifetime in seconds.
#### Default
```ts
600
```
***
### clientStore
> **clientStore**: [`ClientStore`](ClientStore.md)
Defined in: [oauthServerTypes.ts:369](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L369)
App-provided store for dynamic clients.
***
### endpoints?
> `optional` **endpoints?**: `object`
Defined in: [oauthServerTypes.ts:405](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L405)
Override the default endpoint paths.
#### authorize?
> `optional` **authorize?**: `string`
##### Default
```ts
'/authorize'
```
#### register?
> `optional` **register?**: `string`
##### Default
```ts
'/register'
```
#### token?
> `optional` **token?**: `string`
##### Default
```ts
'/token'
```
***
### issuer
> **issuer**: `string`
Defined in: [oauthServerTypes.ts:367](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L367)
The authorization server's issuer identifier (its base URL).
***
### issueTokens
> **issueTokens**: (`args`) => [`IssuedTokens`](IssuedTokens.md) \| `Promise`\<[`IssuedTokens`](IssuedTokens.md)\>
Defined in: [oauthServerTypes.ts:376](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L376)
App-owned token minting. The core never sees the user model or signing keys
— it hands you the subject/scopes/client and you return the tokens.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | [`IssueTokensArgs`](IssueTokensArgs.md) |
#### Returns
[`IssuedTokens`](IssuedTokens.md) \| `Promise`\<[`IssuedTokens`](IssuedTokens.md)\>
***
### onAuthorize
> **onAuthorize**: (`args`) => [`OnAuthorizeResult`](../type-aliases/OnAuthorizeResult.md) \| `Promise`\<[`OnAuthorizeResult`](../type-aliases/OnAuthorizeResult.md)\>
Defined in: [oauthServerTypes.ts:382](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L382)
App-owned login/consent. Called on every authorize request; return the
authenticated subject to approve, or `{ approved: false, redirect }` to send
the user to your own login/consent UI.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | [`OnAuthorizeArgs`](OnAuthorizeArgs.md) |
#### Returns
[`OnAuthorizeResult`](../type-aliases/OnAuthorizeResult.md) \| `Promise`\<[`OnAuthorizeResult`](../type-aliases/OnAuthorizeResult.md)\>
***
### onRefreshToken?
> `optional` **onRefreshToken?**: (`args`) => [`OnRefreshTokenResult`](../type-aliases/OnRefreshTokenResult.md) \| `Promise`\<[`OnRefreshTokenResult`](../type-aliases/OnRefreshTokenResult.md)\>
Defined in: [oauthServerTypes.ts:389](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L389)
App-owned refresh-token validation. Required to support the `refresh_token`
grant; when omitted, refresh requests get `unsupported_grant_type`.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | [`OnRefreshTokenArgs`](OnRefreshTokenArgs.md) |
#### Returns
[`OnRefreshTokenResult`](../type-aliases/OnRefreshTokenResult.md) \| `Promise`\<[`OnRefreshTokenResult`](../type-aliases/OnRefreshTokenResult.md)\>
***
### resource?
> `optional` **resource?**: `string`
Defined in: [oauthServerTypes.ts:398](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L398)
When set, [OAuthHandlers.protectedResourceMetadata](OAuthHandlers.md#protectedresourcemetadata) is served, pairing
this resource URL with the issuer as its authorization server (RFC 9728).
***
### scopesSupported?
> `optional` **scopesSupported?**: `string`[]
Defined in: [oauthServerTypes.ts:393](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L393)
Scopes advertised in discovery metadata (`scopes_supported`).
---
## Interface: OnAuthorizeArgs
Defined in: [oauthServerTypes.ts:325](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L325)
Arguments passed to [OAuthServerOptions.onAuthorize](OAuthServerOptions.md#onauthorize).
## Properties
### client
> **client**: [`OAuthClient`](OAuthClient.md)
Defined in: [oauthServerTypes.ts:327](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L327)
The resolved client making the request.
***
### headers
> **headers**: `Record`\<`string`, `string` \| `undefined`\>
Defined in: [oauthServerTypes.ts:335](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L335)
The inbound request headers, so the app can read its own session cookie
to decide whether the user is authenticated. Runner-agnostic: there is no
framework context here.
***
### request
> **request**: [`AuthorizeRequest`](AuthorizeRequest.md)
Defined in: [oauthServerTypes.ts:329](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L329)
The validated authorization request.
---
## Interface: OnRefreshTokenArgs
Defined in: [oauthServerTypes.ts:351](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L351)
Arguments passed to [OAuthServerOptions.onRefreshToken](OAuthServerOptions.md#onrefreshtoken).
## Properties
### client
> **client**: [`OAuthClient`](OAuthClient.md)
Defined in: [oauthServerTypes.ts:355](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L355)
The authenticated client.
***
### refreshToken
> **refreshToken**: `string`
Defined in: [oauthServerTypes.ts:353](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L353)
The refresh token presented by the client.
***
### scopes
> **scopes**: `string`[]
Defined in: [oauthServerTypes.ts:357](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L357)
Scopes requested in the refresh request (may be empty).
---
## Interface: ProtectedResourceMetadata
Defined in: [protectedResourceMetadata.ts:16](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/protectedResourceMetadata.ts#L16)
RFC 9728 Protected Resource Metadata document.
## Properties
### authorization\_servers
> **authorization\_servers**: `string`[]
Defined in: [protectedResourceMetadata.ts:20](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/protectedResourceMetadata.ts#L20)
Issuer identifiers of the authorization servers that issue for it.
***
### resource
> **resource**: `string`
Defined in: [protectedResourceMetadata.ts:18](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/protectedResourceMetadata.ts#L18)
The resource identifier this document describes.
---
## Interface: RefreshRotation
Defined in: [refreshTokenRotation.ts:68](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/refreshTokenRotation.ts#L68)
The refresh-rotation helpers returned by [createRefreshRotation](../functions/createRefreshRotation.md).
## Properties
### issue
> **issue**: (`args`) => `Promise`\<`string`\>
Defined in: [refreshTokenRotation.ts:74](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/refreshTokenRotation.ts#L74)
Mint and persist a new opaque refresh token, returning the plaintext value
to hand back to the client. Call this from your `issueTokens` hook so every
issued refresh token is tracked for rotation.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | [`IssueRefreshTokenArgs`](IssueRefreshTokenArgs.md) |
#### Returns
`Promise`\<`string`\>
***
### onRefreshToken
> **onRefreshToken**: (`args`) => `Promise`\<[`OnRefreshTokenResult`](../type-aliases/OnRefreshTokenResult.md)\>
Defined in: [refreshTokenRotation.ts:80](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/refreshTokenRotation.ts#L80)
A ready `onRefreshToken` implementation: validates the presented token,
enforces single use, expiry, and per-owner reuse detection, then approves
the refresh. Pass it straight to `createOAuthHandlers`.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | [`OnRefreshTokenArgs`](OnRefreshTokenArgs.md) |
#### Returns
`Promise`\<[`OnRefreshTokenResult`](../type-aliases/OnRefreshTokenResult.md)\>
---
## Interface: RefreshRotationOptions
Defined in: [refreshTokenRotation.ts:37](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/refreshTokenRotation.ts#L37)
Configuration for [createRefreshRotation](../functions/createRefreshRotation.md).
## Properties
### generateToken?
> `optional` **generateToken?**: () => `string`
Defined in: [refreshTokenRotation.ts:49](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/refreshTokenRotation.ts#L49)
Override the opaque-token generator. Defaults to 32 random bytes,
base64url-encoded. Useful for deterministic tests.
#### Returns
`string`
***
### hashToken?
> `optional` **hashToken?**: (`token`) => `string`
Defined in: [refreshTokenRotation.ts:54](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/refreshTokenRotation.ts#L54)
Override the token hashing function used before persistence. Defaults to
SHA-256 (hex). The plaintext token is never stored.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `token` | `string` |
#### Returns
`string`
***
### refreshTokenTtl?
> `optional` **refreshTokenTtl?**: `number`
Defined in: [refreshTokenRotation.ts:44](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/refreshTokenRotation.ts#L44)
Refresh-token lifetime in seconds.
#### Default
```ts
2592000 (30 days)
```
***
### store
> **store**: [`RefreshTokenStore`](RefreshTokenStore.md)
Defined in: [refreshTokenRotation.ts:39](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/refreshTokenRotation.ts#L39)
App-provided persistence for refresh tokens.
---
## Interface: RefreshTokenStore
Defined in: [oauthServerTypes.ts:185](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L185)
App-provided store for refresh tokens, backing OAuth 2.1 rotation. The store
is pure persistence — the rotation mechanics (single-use, expiry, reuse
detection) live in `createRefreshRotation`. Back it with DynamoDB, Postgres,
in-memory, … The "owner" of a token is the `(clientId, subject)` pair.
## Properties
### delete
> **delete**: (`tokenHash`) => `void` \| `Promise`\<`void`\>
Defined in: [oauthServerTypes.ts:193](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L193)
Remove a single refresh token by its hash.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `tokenHash` | `string` |
#### Returns
`void` \| `Promise`\<`void`\>
***
### deleteByOwner
> **deleteByOwner**: (`owner`) => `void` \| `Promise`\<`void`\>
Defined in: [oauthServerTypes.ts:198](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L198)
Remove every refresh token belonging to an owner. Called on reuse detection
to revoke the entire chain (the live token included), forcing re-auth.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `owner` | \{ `clientId`: `string`; `subject`: `string`; \} |
| `owner.clientId` | `string` |
| `owner.subject` | `string` |
#### Returns
`void` \| `Promise`\<`void`\>
***
### get
> **get**: (`tokenHash`) => [`StoredRefreshToken`](StoredRefreshToken.md) \| `Promise`\<[`StoredRefreshToken`](StoredRefreshToken.md) \| `undefined`\> \| `undefined`
Defined in: [oauthServerTypes.ts:189](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L189)
Look up a refresh token by its hash. Return `undefined` if unknown.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `tokenHash` | `string` |
#### Returns
[`StoredRefreshToken`](StoredRefreshToken.md) \| `Promise`\<[`StoredRefreshToken`](StoredRefreshToken.md) \| `undefined`\> \| `undefined`
***
### save
> **save**: (`token`) => `void` \| `Promise`\<`void`\>
Defined in: [oauthServerTypes.ts:187](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L187)
Persist a refresh token, upserting by `tokenHash`.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `token` | [`StoredRefreshToken`](StoredRefreshToken.md) |
#### Returns
`void` \| `Promise`\<`void`\>
---
## Interface: StoredAccessToken
Defined in: [oauthServerTypes.ts:210](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L210)
A persisted opaque access token, stored by its hash (never the plaintext
value) so a store compromise does not leak usable tokens. The same shape
backs both OAuth access tokens and long-lived personal API keys; mint the
opaque value with `generateApiToken` and persist only its `tokenHash`.
## Properties
### clientId
> **clientId**: `string`
Defined in: [oauthServerTypes.ts:214](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L214)
The `client_id` the token was issued to.
***
### createdAt?
> `optional` **createdAt?**: `number`
Defined in: [oauthServerTypes.ts:237](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L237)
Unix timestamp (milliseconds) when the token was created. Set at issuance;
used by listing UIs to show "created on" dates.
***
### displayPrefix?
> `optional` **displayPrefix?**: `string`
Defined in: [oauthServerTypes.ts:232](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L232)
Masked prefix safe to display in listing UIs (e.g. `"oca_3f2a…"`). Set at
issuance from `generateApiToken`'s return value; never recomputable from
the hash alone. Omit for tokens minted without a display prefix.
***
### expiresAt
> **expiresAt**: `number` \| `null`
Defined in: [oauthServerTypes.ts:224](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L224)
Unix timestamp (milliseconds) after which the token is invalid, or `null`
for a token that never expires. `null` is an explicit opt-in for personal
API keys; OAuth access tokens should always set a short lifetime.
***
### lastUsedAt?
> `optional` **lastUsedAt?**: `number`
Defined in: [oauthServerTypes.ts:226](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L226)
Unix timestamp (milliseconds) the token was last presented, for auditing.
***
### scopes
> **scopes**: `string`[]
Defined in: [oauthServerTypes.ts:218](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L218)
The scopes granted to the token.
***
### subject
> **subject**: `string`
Defined in: [oauthServerTypes.ts:216](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L216)
The authenticated end-user subject identifier.
***
### tokenHash
> **tokenHash**: `string`
Defined in: [oauthServerTypes.ts:212](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L212)
SHA-256 hash (hex) of the opaque token. Plaintext is never stored.
---
## Interface: StoredAuthorizationCode
Defined in: [oauthServerTypes.ts:120](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L120)
A short-lived authorization code with its bound PKCE challenge and the
details needed to issue tokens when the code is later exchanged.
## Properties
### clientId
> **clientId**: `string`
Defined in: [oauthServerTypes.ts:124](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L124)
The `client_id` the code was issued to.
***
### code
> **code**: `string`
Defined in: [oauthServerTypes.ts:122](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L122)
The opaque authorization code value.
***
### codeChallenge
> **codeChallenge**: `string`
Defined in: [oauthServerTypes.ts:128](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L128)
The PKCE `code_challenge` (S256) bound to this code.
***
### expiresAt
> **expiresAt**: `number`
Defined in: [oauthServerTypes.ts:134](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L134)
Unix timestamp (milliseconds) after which the code is invalid.
***
### redirectUri
> **redirectUri**: `string`
Defined in: [oauthServerTypes.ts:126](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L126)
The redirect URI the code was issued for (must match on exchange).
***
### scopes
> **scopes**: `string`[]
Defined in: [oauthServerTypes.ts:130](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L130)
The scopes granted to this code.
***
### subject
> **subject**: `string`
Defined in: [oauthServerTypes.ts:132](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L132)
The authenticated end-user subject identifier.
---
## Interface: StoredRefreshToken
Defined in: [oauthServerTypes.ts:160](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L160)
A persisted refresh token, stored by its hash (never the plaintext value) so
a store compromise does not leak usable tokens. Owned by the
[RefreshTokenStore](RefreshTokenStore.md); minted and rotated by `createRefreshRotation`.
## Properties
### clientId
> **clientId**: `string`
Defined in: [oauthServerTypes.ts:164](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L164)
The `client_id` the token was issued to.
***
### consumedAt?
> `optional` **consumedAt?**: `number`
Defined in: [oauthServerTypes.ts:176](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L176)
Unix timestamp (milliseconds) when the token was rotated (consumed). A
consumed token that is presented again signals reuse (theft or a replay)
and triggers revocation of the owner's whole token set.
***
### expiresAt
> **expiresAt**: `number`
Defined in: [oauthServerTypes.ts:170](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L170)
Unix timestamp (milliseconds) after which the token is invalid.
***
### scopes
> **scopes**: `string`[]
Defined in: [oauthServerTypes.ts:168](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L168)
The scopes granted to this token.
***
### subject
> **subject**: `string`
Defined in: [oauthServerTypes.ts:166](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L166)
The authenticated end-user subject identifier.
***
### tokenHash
> **tokenHash**: `string`
Defined in: [oauthServerTypes.ts:162](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L162)
SHA-256 hash (hex) of the opaque refresh token. Plaintext is never stored.
---
## Interface: VerifiedAccessToken
Defined in: [createAccessTokenVerifier.ts:5](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/createAccessTokenVerifier.ts#L5)
The identity resolved from a valid access token.
## Properties
### clientId
> **clientId**: `string`
Defined in: [createAccessTokenVerifier.ts:11](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/createAccessTokenVerifier.ts#L11)
The `client_id` the token was issued to.
***
### scopes
> **scopes**: `string`[]
Defined in: [createAccessTokenVerifier.ts:9](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/createAccessTokenVerifier.ts#L9)
The scopes granted to the token.
***
### subject
> **subject**: `string`
Defined in: [createAccessTokenVerifier.ts:7](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/createAccessTokenVerifier.ts#L7)
The authenticated end-user subject identifier.
---
## Type Alias: AuthHttpRequest
> **AuthHttpRequest** = [`OAuthRequest`](../interfaces/OAuthRequest.md)
Defined in: [oauthServerTypes.ts:15](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L15)
Neutral aliases for the two shapes below. They predate the email/password
flows in `./emailAuth`, which reuse them verbatim, so the `OAuth`-prefixed
names are kept as the originals and these read correctly at the newer call
sites.
---
## Type Alias: AuthHttpResponse
> **AuthHttpResponse** = [`OAuthResponse`](../interfaces/OAuthResponse.md)
Defined in: [oauthServerTypes.ts:17](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L17)
---
## Type Alias: ClientDisplay
> **ClientDisplay** = `object`
Defined in: [redirectConsentOnAuthorize.ts:39](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/redirectConsentOnAuthorize.ts#L39)
Human-readable display fields for an OAuth client, safe to show on a consent
screen. Used by the fallback resolver when the client record omits them.
## Properties
### clientName?
> `optional` **clientName?**: `string`
Defined in: [redirectConsentOnAuthorize.ts:41](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/redirectConsentOnAuthorize.ts#L41)
Human-readable client name to show on the consent screen.
***
### logoUri?
> `optional` **logoUri?**: `string`
Defined in: [redirectConsentOnAuthorize.ts:43](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/redirectConsentOnAuthorize.ts#L43)
URL of the client's logo image.
---
## Type Alias: ConsentGrant
> **ConsentGrant** = `object`
Defined in: [redirectConsentOnAuthorize.ts:12](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/redirectConsentOnAuthorize.ts#L12)
A consent grant stored by `codeChallenge` (PKCE), representing a
previously-approved authorization that the `onAuthorize` hook can consume.
## Properties
### expiresAt
> **expiresAt**: `number`
Defined in: [redirectConsentOnAuthorize.ts:18](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/redirectConsentOnAuthorize.ts#L18)
Unix timestamp (milliseconds) after which the grant is invalid.
***
### scopes
> **scopes**: `string`[]
Defined in: [redirectConsentOnAuthorize.ts:16](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/redirectConsentOnAuthorize.ts#L16)
The scopes the user approved.
***
### subject
> **subject**: `string`
Defined in: [redirectConsentOnAuthorize.ts:14](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/redirectConsentOnAuthorize.ts#L14)
The authenticated end-user subject identifier.
---
## Type Alias: ConsentGrantStore
> **ConsentGrantStore** = `object`
Defined in: [redirectConsentOnAuthorize.ts:26](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/redirectConsentOnAuthorize.ts#L26)
Persistence contract for consent grants, correlated by PKCE `codeChallenge`.
The write side (creating a grant) lives in the application; this interface
covers only what the `onAuthorize` hook needs: read and single-use consume.
## Properties
### deleteConsentGrant
> **deleteConsentGrant**: (`params`) => `Promise`\<`void`\>
Defined in: [redirectConsentOnAuthorize.ts:32](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/redirectConsentOnAuthorize.ts#L32)
Delete a consent grant (called after consumption to enforce single-use).
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `params` | \{ `codeChallenge`: `string`; \} |
| `params.codeChallenge` | `string` |
#### Returns
`Promise`\<`void`\>
***
### getConsentGrant
> **getConsentGrant**: (`params`) => `Promise`\<[`ConsentGrant`](ConsentGrant.md) \| `undefined`\>
Defined in: [redirectConsentOnAuthorize.ts:28](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/redirectConsentOnAuthorize.ts#L28)
Look up a consent grant by its PKCE `codeChallenge`.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `params` | \{ `codeChallenge`: `string`; \} |
| `params.codeChallenge` | `string` |
#### Returns
`Promise`\<[`ConsentGrant`](ConsentGrant.md) \| `undefined`\>
---
## Type Alias: ConsentStoreQuery
> **ConsentStoreQuery** = \<`Row`\>(`params`) => `Promise`\<\{ `rows`: `Row`[]; \}\>
Defined in: [postgresConsentStore.ts:11](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/postgresConsentStore.ts#L11)
Minimal query interface compatible with both `pg` Pool.query and
`@ttoss/lambda-postgres-query`'s `query` function. The caller injects
whichever runner they use; `@ttoss/auth-core` has no database dependency.
## Type Parameters
| Type Parameter | Default type |
| ------ | ------ |
| `Row` *extends* `Record`\<`string`, `unknown`\> | `Record`\<`string`, `unknown`\> |
## Parameters
| Parameter | Type |
| ------ | ------ |
| `params` | \{ `text`: `string`; `values?`: `unknown`[]; \} |
| `params.text` | `string` |
| `params.values?` | `unknown`[] |
## Returns
`Promise`\<\{ `rows`: `Row`[]; \}\>
---
## Type Alias: CreatePostgresConsentStoreOptions
> **CreatePostgresConsentStoreOptions** = `object`
Defined in: [postgresConsentStore.ts:21](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/postgresConsentStore.ts#L21)
Options for [createPostgresConsentStore](../functions/createPostgresConsentStore.md).
## Properties
### query
> **query**: [`ConsentStoreQuery`](ConsentStoreQuery.md)
Defined in: [postgresConsentStore.ts:23](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/postgresConsentStore.ts#L23)
Injected Postgres query runner.
***
### tableName?
> `optional` **tableName?**: `string`
Defined in: [postgresConsentStore.ts:28](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/postgresConsentStore.ts#L28)
Table name for consent grants.
#### Default
```ts
'oauth_consent_grants'
```
---
## Type Alias: CreateRedirectConsentOnAuthorizeOptions
> **CreateRedirectConsentOnAuthorizeOptions** = `object` & [`ConsentGrantStore`](ConsentGrantStore.md)
Defined in: [redirectConsentOnAuthorize.ts:49](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/redirectConsentOnAuthorize.ts#L49)
Options for [createRedirectConsentOnAuthorize](../functions/createRedirectConsentOnAuthorize.md).
## Type Declaration
### clientStore?
> `optional` **clientStore?**: [`ClientStore`](../interfaces/ClientStore.md)
Optional client store used to look up the registered client by id so its
`client_name` and `logo_uri` can be appended to the consent redirect URL.
When omitted, only `getClientDisplayFallback` (if provided) contributes.
### consentUrl
> **consentUrl**: `string`
Base URL of the external consent screen. OAuth parameters are appended as
query-string values: `client_id`, `redirect_uri`, `code_challenge`,
`code_challenge_method`, `scope`, and `state` (when present).
### getClientDisplayFallback?
> `optional` **getClientDisplayFallback?**: (`params`) => [`ClientDisplay`](ClientDisplay.md) \| `undefined`
Optional fallback resolver for display fields when the registered client
record omits `client_name` or `logo_uri`. Receives the `clientId` and the
resolved client record (if any); return a partial [ClientDisplay](ClientDisplay.md) to
fill the gaps. Consumer-owned — ttoss never hard-codes client display data.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `params` | \{ `client?`: [`OAuthClient`](../interfaces/OAuthClient.md); `clientId`: `string`; \} |
| `params.client?` | [`OAuthClient`](../interfaces/OAuthClient.md) |
| `params.clientId` | `string` |
#### Returns
[`ClientDisplay`](ClientDisplay.md) \| `undefined`
---
## Type Alias: EmailAuthDelivery
> **EmailAuthDelivery** = `object`
Defined in: [emailAuthTypes.ts:201](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L201)
Everything the application needs to compose and send one auth email. The
engine mints and persists the token, then hands the plaintext here exactly
once — there is no transport dependency in this package, so the application
sends it with whichever provider it already uses (Resend, SES, SMTP, …).
## Properties
### expires
> **expires**: `Date`
Defined in: [emailAuthTypes.ts:215](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L215)
***
### purpose
> **purpose**: [`OneTimeTokenPurpose`](OneTimeTokenPurpose.md)
Defined in: [emailAuthTypes.ts:204](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L204)
***
### to
> **to**: `string`
Defined in: [emailAuthTypes.ts:203](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L203)
Normalized recipient address.
***
### token
> **token**: `string`
Defined in: [emailAuthTypes.ts:209](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L209)
The plain token. For `emailCode` this is the digit code to show the user;
for the link flows it is already embedded in `url`.
***
### url?
> `optional` **url?**: `string`
Defined in: [emailAuthTypes.ts:214](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L214)
The absolute URL to put behind the call to action, present for every
purpose except `emailCode`. Built from `baseUrl` and the flow's `paths`.
***
### user
> **user**: [`EmailAuthUser`](EmailAuthUser.md) \| `null`
Defined in: [emailAuthTypes.ts:220](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L220)
The user the token was issued for, or `null` when a code was mailed to an
address that has no user row yet.
---
## Type Alias: EmailAuthErrorCode
> **EmailAuthErrorCode** = *typeof* [`emailAuthErrorCodes`](../variables/emailAuthErrorCodes.md)\[`number`\]
Defined in: [emailAuthRuntime.ts:83](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthRuntime.ts#L83)
---
## Type Alias: EmailAuthHandler
> **EmailAuthHandler** = (`request`) => `Promise`\<[`AuthHttpResponse`](AuthHttpResponse.md)\>
Defined in: [emailAuthTypes.ts:362](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L362)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `request` | [`AuthHttpRequest`](AuthHttpRequest.md) |
## Returns
`Promise`\<[`AuthHttpResponse`](AuthHttpResponse.md)\>
---
## Type Alias: EmailAuthHandlers
> **EmailAuthHandlers** = `object`
Defined in: [emailAuthTypes.ts:370](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L370)
The mounted flows. A handler is present only when its mode is enabled, so an
adapter can mount exactly what the application configured.
## Properties
### modes
> **modes**: [`EmailAuthMode`](EmailAuthMode.md)[]
Defined in: [emailAuthTypes.ts:374](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L374)
The modes that were enabled.
***
### paths
> **paths**: `Required`\<[`EmailAuthPaths`](EmailAuthPaths.md)\>
Defined in: [emailAuthTypes.ts:372](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L372)
Resolved paths for every mounted handler.
***
### requestPasswordReset?
> `optional` **requestPasswordReset?**: [`EmailAuthHandler`](EmailAuthHandler.md)
Defined in: [emailAuthTypes.ts:382](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L382)
***
### resetPassword?
> `optional` **resetPassword?**: [`EmailAuthHandler`](EmailAuthHandler.md)
Defined in: [emailAuthTypes.ts:383](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L383)
***
### sendEmailCode?
> `optional` **sendEmailCode?**: [`EmailAuthHandler`](EmailAuthHandler.md)
Defined in: [emailAuthTypes.ts:379](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L379)
***
### sendMagicLink?
> `optional` **sendMagicLink?**: [`EmailAuthHandler`](EmailAuthHandler.md)
Defined in: [emailAuthTypes.ts:377](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L377)
***
### signIn?
> `optional` **signIn?**: [`EmailAuthHandler`](EmailAuthHandler.md)
Defined in: [emailAuthTypes.ts:376](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L376)
***
### signUp?
> `optional` **signUp?**: [`EmailAuthHandler`](EmailAuthHandler.md)
Defined in: [emailAuthTypes.ts:375](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L375)
***
### verifyEmail?
> `optional` **verifyEmail?**: [`EmailAuthHandler`](EmailAuthHandler.md)
Defined in: [emailAuthTypes.ts:381](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L381)
***
### verifyEmailCode?
> `optional` **verifyEmailCode?**: [`EmailAuthHandler`](EmailAuthHandler.md)
Defined in: [emailAuthTypes.ts:380](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L380)
***
### verifyMagicLink?
> `optional` **verifyMagicLink?**: [`EmailAuthHandler`](EmailAuthHandler.md)
Defined in: [emailAuthTypes.ts:378](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L378)
---
## Type Alias: EmailAuthHooks
> **EmailAuthHooks** = `object`
Defined in: [emailAuthTypes.ts:231](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L231)
## Properties
### enrichSession?
> `optional` **enrichSession?**: (`args`) => `Promise`\<[`EmailAuthSession`](EmailAuthSession.md)\> \| [`EmailAuthSession`](EmailAuthSession.md)
Defined in: [emailAuthTypes.ts:242](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L242)
Called after `issueSession`, to fold application state into the response
body without the engine knowing about it.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | \{ `session`: [`EmailAuthSession`](EmailAuthSession.md); `user`: [`EmailAuthUser`](EmailAuthUser.md); \} |
| `args.session` | [`EmailAuthSession`](EmailAuthSession.md) |
| `args.user` | [`EmailAuthUser`](EmailAuthUser.md) |
#### Returns
`Promise`\<[`EmailAuthSession`](EmailAuthSession.md)\> \| [`EmailAuthSession`](EmailAuthSession.md)
***
### onUserCreated?
> `optional` **onUserCreated?**: (`user`) => `Promise`\<`void`\> \| `void`
Defined in: [emailAuthTypes.ts:237](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L237)
Called after a user row is created, before a session is issued. The place
for application-specific bootstrapping (a default workspace, a free-plan
subscription, an analytics identify call).
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `user` | [`EmailAuthUser`](EmailAuthUser.md) |
#### Returns
`Promise`\<`void`\> \| `void`
---
## Type Alias: EmailAuthMode
> **EmailAuthMode** = `"password"` \| `"magicLink"` \| `"emailCode"` \| `"emailVerification"` \| `"passwordReset"`
Defined in: [emailAuthTypes.ts:12](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L12)
The credential flows an application turns on. Each mode mounts its own
handlers and requires its own options, so an application that only signs
users in with a mailed code never exposes a password endpoint.
---
## Type Alias: EmailAuthOptions
> **EmailAuthOptions** = `object`
Defined in: [emailAuthTypes.ts:305](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L305)
## Properties
### baseUrl?
> `optional` **baseUrl?**: `string`
Defined in: [emailAuthTypes.ts:329](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L329)
Absolute base URL of the application the emailed links point at, e.g.
`https://app.example.com`. Required by every mode except `emailCode`.
***
### emailCode?
> `optional` **emailCode?**: [`EmailCodeOptions`](EmailCodeOptions.md)
Defined in: [emailAuthTypes.ts:341](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L341)
***
### hooks?
> `optional` **hooks?**: [`EmailAuthHooks`](EmailAuthHooks.md)
Defined in: [emailAuthTypes.ts:344](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L344)
***
### issueSession
> **issueSession**: (`user`) => `Promise`\<[`EmailAuthSession`](EmailAuthSession.md)\> \| [`EmailAuthSession`](EmailAuthSession.md)
Defined in: [emailAuthTypes.ts:316](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L316)
Mints whatever the application calls a session. Kept as a hook rather than
a built-in because session topology is the one thing consumers genuinely
disagree on — a long-lived JWT and a short access token with a rotating
refresh family are both valid, and neither belongs in this engine.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `user` | [`EmailAuthUser`](EmailAuthUser.md) |
#### Returns
`Promise`\<[`EmailAuthSession`](EmailAuthSession.md)\> \| [`EmailAuthSession`](EmailAuthSession.md)
***
### linkPaths?
> `optional` **linkPaths?**: `object`
Defined in: [emailAuthTypes.ts:335](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L335)
Client-side paths the emailed links land on, appended to `baseUrl` with
`?token=`. Default to `/auth/callback`, `/auth/verify-email` and
`/auth/reset-password`.
#### emailVerification?
> `optional` **emailVerification?**: `string`
#### magicLink?
> `optional` **magicLink?**: `string`
#### passwordReset?
> `optional` **passwordReset?**: `string`
***
### modes
> **modes**: [`EmailAuthMode`](EmailAuthMode.md)[]
Defined in: [emailAuthTypes.ts:307](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L307)
The flows to enable. At least one is required.
***
### oneTimeTokenStore
> **oneTimeTokenStore**: [`OneTimeTokenStore`](OneTimeTokenStore.md)
Defined in: [emailAuthTypes.ts:309](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L309)
***
### password?
> `optional` **password?**: [`PasswordOptions`](PasswordOptions.md)
Defined in: [emailAuthTypes.ts:342](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L342)
***
### paths?
> `optional` **paths?**: [`EmailAuthPaths`](EmailAuthPaths.md)
Defined in: [emailAuthTypes.ts:343](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L343)
***
### requestRateLimit?
> `optional` **requestRateLimit?**: [`RequestRateLimit`](RequestRateLimit.md)
Defined in: [emailAuthTypes.ts:355](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L355)
Caps how often one address can be mailed. Strongly recommended: without it
the send endpoints will mail any address as fast as they are called.
The cap is applied to the request, before the engine looks the address up,
and every request is recorded whether or not mail followed. That is
deliberate — counting only the requests that produced mail would make a
`429` mean "this address has an account", turning the limiter into the
enumeration oracle the rest of the flow is careful to avoid.
***
### sendEmail
> **sendEmail**: (`delivery`) => `Promise`\<`void`\> \| `void`
Defined in: [emailAuthTypes.ts:324](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L324)
Sends one auth email. Anything it throws propagates out of the handler to
the adapter's error handling rather than being folded into a response, so
a delivery outage surfaces as an error the application already reports.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `delivery` | [`EmailAuthDelivery`](EmailAuthDelivery.md) |
#### Returns
`Promise`\<`void`\> \| `void`
***
### ttl?
> `optional` **ttl?**: [`EmailAuthTtl`](EmailAuthTtl.md)
Defined in: [emailAuthTypes.ts:340](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L340)
***
### userStore
> **userStore**: [`EmailAuthUserStore`](EmailAuthUserStore.md)
Defined in: [emailAuthTypes.ts:308](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L308)
---
## Type Alias: EmailAuthPaths
> **EmailAuthPaths** = `object`
Defined in: [emailAuthTypes.ts:293](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L293)
Route paths, so an application can mount the flows under its own scheme.
## Properties
### requestPasswordReset?
> `optional` **requestPasswordReset?**: `string`
Defined in: [emailAuthTypes.ts:301](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L301)
***
### resetPassword?
> `optional` **resetPassword?**: `string`
Defined in: [emailAuthTypes.ts:302](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L302)
***
### sendEmailCode?
> `optional` **sendEmailCode?**: `string`
Defined in: [emailAuthTypes.ts:298](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L298)
***
### sendMagicLink?
> `optional` **sendMagicLink?**: `string`
Defined in: [emailAuthTypes.ts:296](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L296)
***
### signIn?
> `optional` **signIn?**: `string`
Defined in: [emailAuthTypes.ts:295](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L295)
***
### signUp?
> `optional` **signUp?**: `string`
Defined in: [emailAuthTypes.ts:294](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L294)
***
### verifyEmail?
> `optional` **verifyEmail?**: `string`
Defined in: [emailAuthTypes.ts:300](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L300)
***
### verifyEmailCode?
> `optional` **verifyEmailCode?**: `string`
Defined in: [emailAuthTypes.ts:299](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L299)
***
### verifyMagicLink?
> `optional` **verifyMagicLink?**: `string`
Defined in: [emailAuthTypes.ts:297](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L297)
---
## Type Alias: EmailAuthSession
> **EmailAuthSession** = `Record`\<`string`, `unknown`\>
Defined in: [emailAuthTypes.ts:229](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L229)
Whatever the application hands back to the client on a successful
authentication. The engine never inspects it, which is what lets one
application return a bare JWT and another an access token plus a rotating
refresh token.
---
## Type Alias: EmailAuthTtl
> **EmailAuthTtl** = `object`
Defined in: [emailAuthTypes.ts:253](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L253)
Lifetime in seconds for each purpose's token.
## Properties
### emailCode?
> `optional` **emailCode?**: `number`
Defined in: [emailAuthTypes.ts:257](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L257)
Defaults to 10 minutes — a short code needs a short window.
***
### emailVerification?
> `optional` **emailVerification?**: `number`
Defined in: [emailAuthTypes.ts:259](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L259)
Defaults to 24 hours.
***
### magicLink?
> `optional` **magicLink?**: `number`
Defined in: [emailAuthTypes.ts:255](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L255)
Defaults to 24 hours.
***
### passwordReset?
> `optional` **passwordReset?**: `number`
Defined in: [emailAuthTypes.ts:261](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L261)
Defaults to 1 hour.
---
## Type Alias: EmailAuthUser
> **EmailAuthUser** = `object`
Defined in: [emailAuthTypes.ts:40](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L40)
The application's user record, as far as this engine is concerned. Anything
else on the row (name, locale, …) is the application's business and is
carried through untouched by `hooks` and `issueSession`.
## Indexable
> \[`key`: `string`\]: `unknown`
## Properties
### email
> **email**: `string`
Defined in: [emailAuthTypes.ts:42](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L42)
***
### emailVerified?
> `optional` **emailVerified?**: `boolean`
Defined in: [emailAuthTypes.ts:48](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L48)
***
### id
> **id**: `string`
Defined in: [emailAuthTypes.ts:41](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L41)
***
### passwordHash?
> `optional` **passwordHash?**: `string` \| `null`
Defined in: [emailAuthTypes.ts:47](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L47)
The stored password hash, or `null` for a user who has only ever signed in
with a link or a code. Never the plain password.
---
## Type Alias: EmailAuthUserStore
> **EmailAuthUserStore** = `object`
Defined in: [emailAuthTypes.ts:59](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L59)
App-provided user persistence. The engine owns the flow mechanics; the app
owns the table (Sequelize via `@ttoss/postgresdb`, DynamoDB, …).
`findByEmail` receives an already-normalized address, so the app must store
and query addresses in the same normalized form.
## Properties
### create
> **create**: (`args`) => `Promise`\<[`EmailAuthUser`](EmailAuthUser.md)\> \| [`EmailAuthUser`](EmailAuthUser.md)
Defined in: [emailAuthTypes.ts:63](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L63)
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | \{ `email`: `string`; `emailVerified`: `boolean`; `passwordHash`: `string` \| `null`; \} |
| `args.email` | `string` |
| `args.emailVerified` | `boolean` |
| `args.passwordHash` | `string` \| `null` |
#### Returns
`Promise`\<[`EmailAuthUser`](EmailAuthUser.md)\> \| [`EmailAuthUser`](EmailAuthUser.md)
***
### findByEmail
> **findByEmail**: (`email`) => `Promise`\<[`EmailAuthUser`](EmailAuthUser.md) \| `null`\> \| [`EmailAuthUser`](EmailAuthUser.md) \| `null`
Defined in: [emailAuthTypes.ts:60](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L60)
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `email` | `string` |
#### Returns
`Promise`\<[`EmailAuthUser`](EmailAuthUser.md) \| `null`\> \| [`EmailAuthUser`](EmailAuthUser.md) \| `null`
***
### update
> **update**: (`args`) => `Promise`\<[`EmailAuthUser`](EmailAuthUser.md)\> \| [`EmailAuthUser`](EmailAuthUser.md)
Defined in: [emailAuthTypes.ts:68](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L68)
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | \{ `emailVerified?`: `boolean`; `id`: `string`; `passwordHash?`: `string`; \} |
| `args.emailVerified?` | `boolean` |
| `args.id` | `string` |
| `args.passwordHash?` | `string` |
#### Returns
`Promise`\<[`EmailAuthUser`](EmailAuthUser.md)\> \| [`EmailAuthUser`](EmailAuthUser.md)
---
## Type Alias: EmailCodeOptions
> **EmailCodeOptions** = `object`
Defined in: [emailAuthTypes.ts:264](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L264)
## Properties
### createUserOnVerify?
> `optional` **createUserOnVerify?**: `boolean`
Defined in: [emailAuthTypes.ts:276](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L276)
Whether verifying a code for an unknown address creates the user, making
the code flow a combined sign-up and sign-in. Defaults to `true`.
***
### digits?
> `optional` **digits?**: `number`
Defined in: [emailAuthTypes.ts:266](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L266)
Number of digits. Defaults to 6.
***
### maxAttempts?
> `optional` **maxAttempts?**: `number`
Defined in: [emailAuthTypes.ts:271](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L271)
Wrong guesses a single code tolerates before it is destroyed. Defaults
to 5. Requires `oneTimeTokenStore.incrementAttempts`.
---
## Type Alias: GeneratedApiToken
> **GeneratedApiToken** = `object`
Defined in: [apiToken.ts:11](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/apiToken.ts#L11)
Primitives for long-lived API tokens (personal access tokens).
Tokens look like `_<64 hex chars>` — e.g. `myapp_3f2a…` — so they
are recognizable in logs and secret scanners. The application stores only
the SHA-256 hash and the display prefix, never the plain token.
## Properties
### displayPrefix
> **displayPrefix**: `string`
Defined in: [apiToken.ts:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/apiToken.ts#L24)
First characters of the token, safe to persist for display purposes
(e.g., `myapp_3f2a…`).
***
### token
> **token**: `string`
Defined in: [apiToken.ts:15](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/apiToken.ts#L15)
The plain token to show to the user once, at creation time.
***
### tokenHash
> **tokenHash**: `string`
Defined in: [apiToken.ts:19](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/apiToken.ts#L19)
SHA-256 hash of the token, safe to persist and index for lookups.
---
## Type Alias: GeneratedAuthorizationCode
> **GeneratedAuthorizationCode** = `object`
Defined in: [oauth.ts:38](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L38)
## Properties
### code
> **code**: `string`
Defined in: [oauth.ts:40](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L40)
Raw code to embed in the redirect. Show once; never persist.
***
### codeHash
> **codeHash**: `string`
Defined in: [oauth.ts:42](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L42)
SHA-256 hex of `code`. Persist this alongside bound metadata.
---
## Type Alias: JwtPayload
> **JwtPayload** = `Record`\<`string`, `unknown`\> & `object`
Defined in: [jwt.ts:28](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/jwt.ts#L28)
## Type Declaration
### exp?
> `optional` **exp?**: `number`
Expiration time, in seconds since epoch. Added automatically by `signJwt`
when `expiresInSeconds` is provided.
### iat?
> `optional` **iat?**: `number`
Issued at, in seconds since epoch. Added automatically by `signJwt`.
---
## Type Alias: OAuthErrorCode
> **OAuthErrorCode** = *typeof* [`oauthErrorCodes`](../variables/oauthErrorCodes.md)\[`number`\]
Defined in: [oauth.ts:162](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L162)
---
## Type Alias: OnAuthorizeResult
> **OnAuthorizeResult** = \{ `approved`: `true`; `scopes?`: `string`[]; `subject`: `string`; \} \| \{ `approved`: `false`; `body?`: `unknown`; `redirect?`: `string`; `status?`: `number`; \}
Defined in: [oauthServerTypes.ts:346](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L346)
Result of the app's consent/login hook.
`approved: true` issues a code and redirects back to the client. When the
user is not authenticated, return `approved: false` with a `redirect` to your
own login page (the adapter performs the redirect), or a `status`/`body` to
render an inline response.
---
## Type Alias: OnRefreshTokenResult
> **OnRefreshTokenResult** = \{ `scopes`: `string`[]; `subject`: `string`; \} \| `undefined`
Defined in: [oauthServerTypes.ts:361](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauthServerTypes.ts#L361)
Result of validating a refresh token. Return `undefined` to reject.
---
## Type Alias: OneTimeToken
> **OneTimeToken** = `object`
Defined in: [oneTimeToken.ts:52](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oneTimeToken.ts#L52)
## Properties
### expires
> **expires**: `Date`
Defined in: [oneTimeToken.ts:62](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oneTimeToken.ts#L62)
***
### token
> **token**: `string`
Defined in: [oneTimeToken.ts:57](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oneTimeToken.ts#L57)
The plain token to deliver to the user (e.g., in a link sent by email).
Never store it — store `tokenHash` instead.
***
### tokenHash
> **tokenHash**: `string`
Defined in: [oneTimeToken.ts:61](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oneTimeToken.ts#L61)
SHA-256 hash of the token, safe to persist.
---
## Type Alias: OneTimeTokenFormat
> **OneTimeTokenFormat** = `"hex"` \| `"numeric"`
Defined in: [oneTimeToken.ts:20](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oneTimeToken.ts#L20)
How the plain token is encoded.
`hex` produces a high-entropy string for tokens that travel inside a link
the user clicks. `numeric` produces a short digit code the user retypes from
their email or SMS — human-transcribable, and therefore low-entropy enough
that it is only safe with a short lifetime and a bounded attempt count.
---
## Type Alias: OneTimeTokenPurpose
> **OneTimeTokenPurpose** = `"magicLink"` \| `"emailCode"` \| `"emailVerification"` \| `"passwordReset"`
Defined in: [emailAuthTypes.ts:28](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L28)
Why a one-time token was issued. Persisted alongside the hash so a token
minted for one flow can never be redeemed by another.
---
## Type Alias: OneTimeTokenStore
> **OneTimeTokenStore** = `object`
Defined in: [emailAuthTypes.ts:104](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L104)
App-provided one-time token persistence.
Every method takes or returns a `tokenHash`, never a redeemable token, which
makes storing a usable secret impossible rather than merely discouraged.
## Properties
### delete
> **delete**: (`args`) => `Promise`\<`void`\> \| `void`
Defined in: [emailAuthTypes.ts:125](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L125)
Delete a token, enforcing single use.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | \{ `purpose`: [`OneTimeTokenPurpose`](OneTimeTokenPurpose.md); `tokenHash`: `string`; \} |
| `args.purpose` | [`OneTimeTokenPurpose`](OneTimeTokenPurpose.md) |
| `args.tokenHash` | `string` |
#### Returns
`Promise`\<`void`\> \| `void`
***
### deleteFor
> **deleteFor**: (`args`) => `Promise`\<`void`\> \| `void`
Defined in: [emailAuthTypes.ts:133](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L133)
Delete every outstanding token of this purpose for this address, so
issuing a new one invalidates whatever preceded it.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | \{ `email`: `string`; `purpose`: [`OneTimeTokenPurpose`](OneTimeTokenPurpose.md); \} |
| `args.email` | `string` |
| `args.purpose` | [`OneTimeTokenPurpose`](OneTimeTokenPurpose.md) |
#### Returns
`Promise`\<`void`\> \| `void`
***
### find
> **find**: (`args`) => `Promise`\<[`StoredOneTimeToken`](StoredOneTimeToken.md) \| `null`\> \| [`StoredOneTimeToken`](StoredOneTimeToken.md) \| `null`
Defined in: [emailAuthTypes.ts:111](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L111)
Look up by hash **and** purpose, so a token minted for one flow cannot be
redeemed by another. This is the lookup for the link flows, where the
token itself is the only thing the request carries.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | \{ `purpose`: [`OneTimeTokenPurpose`](OneTimeTokenPurpose.md); `tokenHash`: `string`; \} |
| `args.purpose` | [`OneTimeTokenPurpose`](OneTimeTokenPurpose.md) |
| `args.tokenHash` | `string` |
#### Returns
`Promise`\<[`StoredOneTimeToken`](StoredOneTimeToken.md) \| `null`\> \| [`StoredOneTimeToken`](StoredOneTimeToken.md) \| `null`
***
### findByEmail?
> `optional` **findByEmail?**: (`args`) => `Promise`\<[`StoredOneTimeToken`](StoredOneTimeToken.md) \| `null`\> \| [`StoredOneTimeToken`](StoredOneTimeToken.md) \| `null`
Defined in: [emailAuthTypes.ts:120](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L120)
Look up the outstanding token for an address. Required when `emailCode` is
enabled: a wrong code hashes to nothing on record, so the engine has to
find the record by address before it can compare and count the attempt.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | \{ `email`: `string`; `purpose`: [`OneTimeTokenPurpose`](OneTimeTokenPurpose.md); \} |
| `args.email` | `string` |
| `args.purpose` | [`OneTimeTokenPurpose`](OneTimeTokenPurpose.md) |
#### Returns
`Promise`\<[`StoredOneTimeToken`](StoredOneTimeToken.md) \| `null`\> \| [`StoredOneTimeToken`](StoredOneTimeToken.md) \| `null`
***
### incrementAttempts?
> `optional` **incrementAttempts?**: (`args`) => `Promise`\<`void`\> \| `void`
Defined in: [emailAuthTypes.ts:142](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L142)
Record a failed attempt. Required when `emailCode` is enabled; the engine
calls it on every wrong guess and destroys the token once `maxAttempts` is
reached.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | \{ `purpose`: [`OneTimeTokenPurpose`](OneTimeTokenPurpose.md); `tokenHash`: `string`; \} |
| `args.purpose` | [`OneTimeTokenPurpose`](OneTimeTokenPurpose.md) |
| `args.tokenHash` | `string` |
#### Returns
`Promise`\<`void`\> \| `void`
***
### save
> **save**: (`token`) => `Promise`\<`void`\> \| `void`
Defined in: [emailAuthTypes.ts:105](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L105)
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `token` | [`StoredOneTimeToken`](StoredOneTimeToken.md) |
#### Returns
`Promise`\<`void`\> \| `void`
---
## Type Alias: PasswordOptions
> **PasswordOptions** = `object`
Defined in: [emailAuthTypes.ts:279](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L279)
## Properties
### minLength?
> `optional` **minLength?**: `number`
Defined in: [emailAuthTypes.ts:281](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L281)
Minimum plain-password length. Defaults to 8.
***
### requireVerifiedEmail?
> `optional` **requireVerifiedEmail?**: `boolean`
Defined in: [emailAuthTypes.ts:289](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L289)
Whether `signIn` rejects a user whose address is unconfirmed.
***
### signInOnSignUp?
> `optional` **signInOnSignUp?**: `boolean`
Defined in: [emailAuthTypes.ts:287](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L287)
Whether `signUp` issues a session immediately, or withholds it until the
address is confirmed. Defaults to `false` when `emailVerification` is
enabled and `true` otherwise.
---
## Type Alias: RequestRateLimit
> **RequestRateLimit** = `object`
Defined in: [emailAuthTypes.ts:177](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L177)
## Properties
### cooldownSeconds?
> `optional` **cooldownSeconds?**: `number`
Defined in: [emailAuthTypes.ts:184](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L184)
Minimum seconds between two requests for the same address and purpose.
Defaults to 60 — long enough to stop a hammering loop, short enough that a
user who mistypes their address is not stuck waiting.
***
### maxPerWindow?
> `optional` **maxPerWindow?**: `number`
Defined in: [emailAuthTypes.ts:186](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L186)
Requests allowed per address per window. Defaults to 10.
***
### store
> **store**: [`RequestRateLimitStore`](RequestRateLimitStore.md)
Defined in: [emailAuthTypes.ts:178](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L178)
***
### windowSeconds?
> `optional` **windowSeconds?**: `number`
Defined in: [emailAuthTypes.ts:188](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L188)
Window the ceiling applies over. Defaults to 24 hours.
---
## Type Alias: RequestRateLimitStore
> **RequestRateLimitStore** = `object`
Defined in: [emailAuthTypes.ts:159](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L159)
App-provided record of how often each address has asked for mail.
Without this, anyone can point the "mail me something" endpoints at a
stranger's address and make the application send to it repeatedly. Capping how
many codes are *valid* does not help — that limits redemptions, not messages.
## Properties
### recent
> **recent**: (`args`) => `Promise`\<`Date`[]\> \| `Date`[]
Defined in: [emailAuthTypes.ts:164](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L164)
Timestamps of the requests recorded for this address and purpose at or
after `since`, in any order.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | \{ `email`: `string`; `purpose`: [`OneTimeTokenPurpose`](OneTimeTokenPurpose.md); `since`: `Date`; \} |
| `args.email` | `string` |
| `args.purpose` | [`OneTimeTokenPurpose`](OneTimeTokenPurpose.md) |
| `args.since` | `Date` |
#### Returns
`Promise`\<`Date`[]\> \| `Date`[]
***
### record
> **record**: (`args`) => `Promise`\<`void`\> \| `void`
Defined in: [emailAuthTypes.ts:170](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L170)
Record one request.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `args` | \{ `email`: `string`; `purpose`: [`OneTimeTokenPurpose`](OneTimeTokenPurpose.md); `requestedAt`: `Date`; \} |
| `args.email` | `string` |
| `args.purpose` | [`OneTimeTokenPurpose`](OneTimeTokenPurpose.md) |
| `args.requestedAt` | `Date` |
#### Returns
`Promise`\<`void`\> \| `void`
---
## Type Alias: Rfc8414Metadata
> **Rfc8414Metadata** = `object`
Defined in: [oauth.ts:185](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L185)
## Properties
### authorization\_endpoint
> **authorization\_endpoint**: `string`
Defined in: [oauth.ts:187](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L187)
***
### code\_challenge\_methods\_supported
> **code\_challenge\_methods\_supported**: \[`"S256"`\]
Defined in: [oauth.ts:192](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L192)
***
### grant\_types\_supported
> **grant\_types\_supported**: \[`"authorization_code"`\]
Defined in: [oauth.ts:191](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L191)
***
### issuer
> **issuer**: `string`
Defined in: [oauth.ts:186](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L186)
***
### registration\_endpoint?
> `optional` **registration\_endpoint?**: `string`
Defined in: [oauth.ts:189](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L189)
***
### response\_types\_supported
> **response\_types\_supported**: \[`"code"`\]
Defined in: [oauth.ts:190](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L190)
***
### token\_endpoint
> **token\_endpoint**: `string`
Defined in: [oauth.ts:188](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L188)
***
### token\_endpoint\_auth\_methods\_supported
> **token\_endpoint\_auth\_methods\_supported**: \[`"none"`\]
Defined in: [oauth.ts:193](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L193)
---
## Type Alias: Rfc9728Metadata
> **Rfc9728Metadata** = `object`
Defined in: [oauth.ts:196](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L196)
## Properties
### authorization\_servers
> **authorization\_servers**: `string`[]
Defined in: [oauth.ts:198](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L198)
***
### resource
> **resource**: `string`
Defined in: [oauth.ts:197](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L197)
---
## Type Alias: StoredOneTimeToken
> **StoredOneTimeToken** = `object`
Defined in: [emailAuthTypes.ts:83](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L83)
A persisted one-time token. Only the hash is stored, so a store dump yields
nothing redeemable.
`email` is carried alongside `userId` because the code flow can mint a token
for an address that has no user row yet, and because a wrong code has to be
counted against a record found by address rather than by its own hash.
## Properties
### attempts?
> `optional` **attempts?**: `number`
Defined in: [emailAuthTypes.ts:95](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L95)
Wrong guesses recorded so far. Only meaningful for `emailCode`, whose
short keyspace has to be defended by a bounded attempt count.
***
### email
> **email**: `string`
Defined in: [emailAuthTypes.ts:86](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L86)
Normalized address the token was mailed to.
***
### expires
> **expires**: `Date`
Defined in: [emailAuthTypes.ts:90](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L90)
***
### purpose
> **purpose**: [`OneTimeTokenPurpose`](OneTimeTokenPurpose.md)
Defined in: [emailAuthTypes.ts:89](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L89)
***
### tokenHash
> **tokenHash**: `string`
Defined in: [emailAuthTypes.ts:84](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L84)
***
### userId
> **userId**: `string` \| `null`
Defined in: [emailAuthTypes.ts:88](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthTypes.ts#L88)
`null` when the token was minted before the user row existed.
---
## Variable: MAX\_NUMERIC\_DIGITS
> `const` **MAX\_NUMERIC\_DIGITS**: `12` = `12`
Defined in: [oneTimeToken.ts:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oneTimeToken.ts#L24)
---
## Variable: MIN\_NUMERIC\_DIGITS
> `const` **MIN\_NUMERIC\_DIGITS**: `4` = `4`
Defined in: [oneTimeToken.ts:22](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oneTimeToken.ts#L22)
---
## Variable: emailAuthErrorCodes
> `const` **emailAuthErrorCodes**: readonly \[`"invalid_request"`, `"invalid_credentials"`, `"email_exists"`, `"invalid_token"`, `"expired_token"`, `"too_many_attempts"`, `"too_many_requests"`, `"email_not_verified"`, `"password_too_weak"`\]
Defined in: [emailAuthRuntime.ts:71](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/emailAuthRuntime.ts#L71)
Error codes a handler can return. Stable strings, so a client can branch on
them without parsing prose.
---
## Variable: oauthErrorCodes
> `const` **oauthErrorCodes**: readonly \[`"invalid_request"`, `"invalid_client"`, `"invalid_grant"`, `"unsupported_grant_type"`, `"access_denied"`, `"server_error"`\]
Defined in: [oauth.ts:153](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/oauth.ts#L153)
---
## @ttoss/auth-core
Framework-agnostic authentication primitives for Node.js, with zero
dependencies beyond `node:crypto` (Amazon Cognito verification and generic
OIDC verification excepted).
## Installation
```bash
pnpm add @ttoss/auth-core
```
## Password hashing
PBKDF2-HMAC-SHA256 with 600,000 iterations (OWASP recommendation) and
constant-time comparison. Hashes are self-describing
(`pbkdf2-sha256$$$`), so iterations can be raised
later without invalidating stored hashes. The legacy `salt:hash` format is
still verified for backwards compatibility.
```ts
const stored = await hashPassword('my-password');
const isMatch = await comparePassword('my-password', stored);
// On successful login, upgrade weak/legacy hashes:
if (isMatch && needsRehash(stored)) {
await saveHash(await hashPassword('my-password'));
}
```
## JWT (HS256)
Sign and verify JWTs for self-hosted authentication, where the application
owns the signing secret. `verifyJwt` returns `null` for malformed, badly
signed, or expired tokens.
```ts
const token = signJwt({
payload: { sub: 'user_123', email: 'user@example.com' },
secret: process.env.JWT_SECRET,
expiresInSeconds: 60 * 60 * 24 * 7, // 7 days
});
const payload = verifyJwt({ token, secret: process.env.JWT_SECRET });
```
For Amazon Cognito tokens, use `@ttoss/auth-core/amazon-cognito`, which
re-exports [`aws-jwt-verify`](https://github.com/awslabs/aws-jwt-verify).
For any other standards-compliant OIDC provider (Entra ID, Okta, Auth0,
Google, …), use `@ttoss/auth-core/oidc` — see [OIDC](#oidc) below.
## OIDC
`createOidcVerifier` builds a token verifier for any OIDC provider with no
manual JWKS wiring: it fetches the provider's `/.well-known/openid-configuration`
document to discover its signing keys, caches them, handles key rotation
transparently, and verifies the token's signature, issuer, and expiry.
```ts
const verifyToken = createOidcVerifier({
issuer: 'https://login.microsoftonline.com//v2.0',
});
const payload = await verifyToken(bearerToken);
```
Audience / resource-indicator validation is intentionally left to the
caller — the expected audience is a property of the resource server, not the
identity provider. When wiring this into `@ttoss/http-server-mcp`, pass
`resourceIndicator` alongside `verifyToken`:
```ts
const mcpRouter = createMcpRouter(mcpServer, {
auth: {
verifyToken: createOidcVerifier({
issuer: 'https://login.microsoftonline.com//v2.0',
}),
resourceIndicator: 'https://mcp.example.com',
},
});
```
Create one verifier at startup and reuse it across requests — discovery and
the JWKS cache are scoped to the verifier instance, not the process.
## One-time tokens
Building block for magic links, email verification, and password reset.
Store only `tokenHash` and `expires`; send `token` to the user and destroy
the record after a successful verification.
```ts
const { token, tokenHash, expires } = generateOneTimeToken({
expiresInSeconds: 60 * 60, // 1 hour, e.g. for password reset
});
// later, when the user clicks the link:
const isValid = verifyOneTimeToken({ token: received, tokenHash, expires });
```
Pass `format: 'numeric'` for a short code the user retypes from their email
instead of a link they click. Digits are drawn by rejection sampling so the
keyspace stays uniform, and the lifetime defaults to 10 minutes rather than 24
hours because ~20 bits of entropy makes a long window a guessing window.
```ts
const { token, tokenHash, expires } = generateOneTimeToken({
format: 'numeric',
digits: 6, // default; 4 to 12 supported
});
```
A short code is only safe with a bounded attempt count, which
`createEmailAuthHandlers` below enforces. Rolling your own means bounding the
guesses yourself.
## Email and password flows
`createEmailAuthHandlers` composes the primitives above into the credential
flows an application actually mounts — password sign-up and sign-in, magic
links, mailed numeric codes, address confirmation, and password reset. It stays
true to the package's contract: no database and no mail transport. Persistence
arrives as stores, session minting as `issueSession`, and delivery as
`sendEmail`, which receives the plaintext token exactly once and sends it with
whichever provider the application already uses.
`modes` decides which flows exist, so an application that only signs users in
with a mailed code never exposes a password endpoint.
```ts
const handlers = createEmailAuthHandlers({
modes: ['emailCode'],
userStore: {
findByEmail: (email) => db.User.findOne({ where: { email } }),
create: ({ email, passwordHash, emailVerified }) =>
db.User.create({ email, passwordHash, emailVerified }),
update: ({ id, ...changes }) => db.User.update(changes, { where: { id } }),
},
oneTimeTokenStore: {
/* save, find, findByEmail, delete, deleteFor, incrementAttempts */
},
issueSession: (user) => issueSession(user),
sendEmail: async ({ to, purpose, token, url, expires }) => {
await ses.send(buildAuthEmail({ to, purpose, token, url, expires }));
},
baseUrl: process.env.APP_URL,
ttl: { emailCode: 60 * 10 },
emailCode: { digits: 6, maxAttempts: 5 },
hooks: {
onUserCreated: (user) => createDefaultWorkspace(user),
enrichSession: ({ session, user }) => ({
...session,
plan: planFor(user),
}),
},
});
```
Each handler takes a normalized request and resolves to a status and a body, so
it is mountable on any runner. For Koa, `emailAuth()` from
[`@ttoss/http-server-auth`](https://ttoss.dev/docs/modules/packages/http-server-auth)
does it for you.
Every handler returns expected outcomes as responses — `invalid_credentials`,
`invalid_token`, `expired_token`, `too_many_attempts` and friends, under a
stable `error.code`. Only genuinely unexpected failures throw, `sendEmail`
included, so a delivery outage reaches the application's error reporting rather
than being folded into a 200.
Two behaviours are deliberate and worth knowing before you diff them against
your own implementation. The endpoints that mail something always return the
same acknowledgement whether or not the address is on file, so the response
cannot be used to enumerate accounts; and sign-in runs a decoy PBKDF2 compare
for an unknown address, so response time cannot either.
### Capping how often an address is mailed
Pass `requestRateLimit` and the send endpoints stop being a way to mail a
stranger repeatedly. Without it they will send as fast as they are called —
issuing a new token invalidates the previous one, which limits how many tokens
are _redeemable_ rather than how many messages go out.
```ts
requestRateLimit: {
store: myRateLimitStore, // { recent, record }
cooldownSeconds: 60, // default
maxPerWindow: 10, // default
windowSeconds: 60 * 60 * 24, // default
}
```
The cap is applied to the request, before the engine looks the address up, and
**every** request is recorded whether or not mail followed. Counting only the
requests that produced mail would make a `429` mean "this address has an
account" — reintroducing the enumeration oracle the rest of the flow avoids.
`createMemoryRequestRateLimitStore` is a reference implementation. Back it with
something shared in production: a per-process limiter caps each replica
separately, so a fleet of N sends N times the intended rate.
## API tokens
Personal access tokens in the form `_`, recognizable in logs and
secret scanners. Show the plain token once; persist only the SHA-256 hash and
a short display prefix.
```ts
const { token, tokenHash, displayPrefix } = generateApiToken({
prefix: 'myapp',
});
const isValid = verifyApiToken({
token: received,
tokenHash,
expiresAt: storedExpiresAt, // optional
});
```
## Encryption at rest
AES-256-GCM helpers for storing sensitive values (e.g., third-party API
keys) in a database. The ciphertext is a single base64 string containing
the IV, auth tag, and payload. Decryption throws on a wrong key or
tampered ciphertext.
```ts
decryptValue,
encryptValue,
generateEncryptionKey,
} from '@ttoss/auth-core';
// Generate once and store in a secret manager:
const key = generateEncryptionKey(); // 64-char hex (32 bytes)
const ciphertext = encryptValue({ plaintext: 'third-party-api-key', key });
const plaintext = decryptValue({ ciphertext, key });
```
## Webhook signatures
HMAC-SHA256 payload signing using the common `sha256=` header
convention (e.g., GitHub's `X-Hub-Signature-256`), with constant-time
verification on the receiving side.
```ts
generateWebhookSecret,
signWebhookPayload,
verifyWebhookSignature,
} from '@ttoss/auth-core';
// Sender:
const secret = generateWebhookSecret();
const signature = signWebhookPayload({ payload: body, secret });
// send as a header, e.g. `X-Myapp-Signature: ${signature}`
// Receiver:
const isValid = verifyWebhookSignature({ payload: body, secret, signature });
```
## Encoding helpers
```ts
const encoded = encode({ id: 1 }); // base64 JSON
const obj = decode(encoded);
```
## OAuth 2.1 authorization server
`createOAuthHandlers` is a **runner-agnostic** OAuth 2.1 authorization-server engine: it implements the authorize/token/register flow and discovery metadata (RFC 8414, 7591, 7636, 6749, 9728) on top of the PKCE/code/JWT primitives above. It operates on plain `{ query, body, headers }` → `{ status, body, redirect }` objects, with no HTTP framework coupling, so any runtime (Koa, AWS Lambda, GraphQL) can host it through a thin adapter — [`@ttoss/http-server-auth`](https://ttoss.dev/docs/modules/packages/http-server-auth) ships the Koa one as `oauthServer()`.
```ts
const oauth = createOAuthHandlers({
issuer,
clientStore,
authCodeStore,
issueTokens,
onAuthorize,
});
const res = await oauth.token({ query: {}, body, headers }); // { status, body }
```
Your app keeps its user model, signing keys, and login/consent UI behind the hooks. See the [OAuth Authorization Server](https://ttoss.dev/docs/engineering/guidelines/oauth-authorization-server) guideline for the full flow.
### Protected resource metadata (RFC 9728)
Three helpers own the RFC 9728 document — its shape, where it is served, and the `WWW-Authenticate` value that points clients at it. They live here so every consumer derives the same answers; `oauthServer`, `createProtectedResourceMetadataMiddleware` and `@ttoss/http-server-mcp`'s router all build on them.
```ts
protectedResourceMetadataDocument,
protectedResourceMetadataPaths,
protectedResourceMetadataUrl,
} from '@ttoss/auth-core';
protectedResourceMetadataPaths({ resource: 'https://host/mcp' });
// => ['/.well-known/oauth-protected-resource/mcp',
// '/.well-known/oauth-protected-resource']
protectedResourceMetadataUrl({ resource: 'https://host/mcp' });
// => 'https://host/.well-known/oauth-protected-resource/mcp'
```
The subtlety worth centralising: RFC 9728 §3.1 derives the metadata URL by inserting the well-known segment **between the host and the resource's path** — `https://host/mcp` is discovered at `https://host/.well-known/oauth-protected-resource/mcp`, not at `https://host/mcp/.well-known/…` and not only at the root. A server that answers only at the root fails a client that applies the rule, so `protectedResourceMetadataPaths` returns every location the document must be served at (de-duplicated to just the root for an origin-only resource). `getWwwAuthenticateHeader` advertises the derived URL.
The two differ on a malformed `resource` on purpose: `protectedResourceMetadataPaths` falls back to the root, because a path is matched against incoming requests and a bad value must not crash route registration, while `protectedResourceMetadataUrl` **throws**, because its result is handed to clients in a response header where an unparseable URL is a dead end they cannot work around and nobody operating the server would see.
### Client secrets
`hashClientSecret` and `verifyClientSecret` hash a `client_secret` with SHA-256 and compare a presented value against a stored hash in constant time. Plain SHA-256 is deliberate: a registered secret is 32 random bytes, so there is no low-entropy guess space for `hashPassword`'s PBKDF2 to slow down.
Implement the optional `ClientStore.verifyClientSecret` to use them, and the raw secret never has to be recoverable — the engine hands your store the presented value instead of comparing the one `get` returned. A store that omits the method makes the engine fall back to comparing `get`'s `client_secret`, which requires keeping that value recoverable.
### Refresh token rotation
`createRefreshRotation` implements opaque, server-stored refresh tokens with OAuth 2.1 rotation against any `RefreshTokenStore`: single use, expiry, scope narrowing, and reuse detection (replaying a rotated token revokes the owner's whole token set). Only token hashes are persisted. Wire `issue` into `issueTokens` and pass the ready `onRefreshToken` straight through.
```ts
const refresh = createRefreshRotation({ store: refreshTokenStore });
createOAuthHandlers({
// …,
issueTokens: async ({ subject, scopes, client }) => ({
accessToken: signJwt({
payload: { sub: subject },
secret,
expiresInSeconds: 3600,
}),
refreshToken: await refresh.issue({ client, subject, scopes }),
expiresIn: 3600,
}),
onRefreshToken: refresh.onRefreshToken,
});
```
### Opaque access tokens
`createAccessTokenVerifier` verifies opaque, server-stored access tokens (and long-lived personal API keys) against any `AccessTokenStore`. Tokens are stored **hash-at-rest** — only the SHA-256 hash crosses the store boundary, so a store compromise leaks nothing usable. Verification is **default-deny** (an unknown or expired token returns `null` without revealing whether it ever existed) and **revocation is immediate** (a token removed via `delete`/`deleteBySubject` fails the next call). Mint the opaque value with `generateApiToken`; its default hashing matches the verifier, so no extra wiring is needed.
```ts
// Issue: persist only the hash; show the plain token to the user once.
const { token, tokenHash } = generateApiToken({ prefix: 'myapp' });
await store.save({
tokenHash,
subject: 'user_123',
scopes: ['read'],
clientId,
expiresAt: Date.now() + 3600_000, // null = never expires (personal API keys)
});
// Verify (e.g. inside an MCP/HTTP auth layer).
const verify = createAccessTokenVerifier({ store, touchLastUsed: true });
const identity = await verify(bearerToken); // VerifiedAccessToken | null
```
Prefer short-lived signed JWT access tokens (`signJwt`/`verifyJwt`) with refresh rotation when statelessness matters; reach for the opaque store when you need revocable access tokens or API keys.
`StoredAccessToken` carries two optional display fields useful for token-management UIs:
- `displayPrefix` — a masked safe-to-show value (e.g. `"oca_3f2a…"`) generated by `generateApiToken`, so users can identify a token without exposing the full secret.
- `createdAt` — Unix timestamp (ms) when the token was issued, for sorted listing.
`AccessTokenStore` also accepts an optional `listBySubject(subject)` method. When implemented, it enables listing all active tokens for a user — useful for "Your active sessions" or "Personal access tokens" management pages.
```ts
const tokens = await store.listBySubject!('user_123');
// [{ tokenHash, displayPrefix, createdAt, expiresAt, scopes, … }, …]
```
### Consent-redirect enrichment
`createRedirectConsentOnAuthorize` accepts two optional parameters for enriching the consent-screen redirect URL with client display data:
- `clientStore` — fetches the registered `OAuthClient` record by `client_id`. When found, `client_name` and `logo_uri` fields are appended as query parameters so the consent screen can display them without a separate API call.
- `getClientDisplayFallback` — called with `{ clientId, client? }` when the registered record is absent or missing display fields. Return a partial `ClientDisplay` (`{ clientName?, logoUri? }`) to fill the gaps. Consumer-owned — ttoss never hard-codes client display data.
```ts
createRedirectConsentOnAuthorize,
type ClientDisplay,
} from '@ttoss/auth-core';
const onAuthorize = createRedirectConsentOnAuthorize({
consentUrl: 'https://app.example.com/consent',
getConsentGrant,
deleteConsentGrant,
clientStore,
getClientDisplayFallback: ({ clientId }): ClientDisplay => ({
clientName: clientNames[clientId],
logoUri: clientLogos[clientId],
}),
});
```
### In-memory reference stores
`createMemoryClientStore`, `createMemoryAuthCodeStore`, `createMemoryRefreshTokenStore`, and `createMemoryAccessTokenStore` are `Map`-backed implementations of the store contracts — for tests, local development, and examples. Production swaps in a durable backend behind the same interfaces.
`createMemoryAccessTokenStore` implements `listBySubject` and round-trips `displayPrefix`/`createdAt` for tests and local development.
`createMemoryUserStore` and `createMemoryOneTimeTokenStore` do the same for the email and password flows, including the attempt counting the `emailCode` mode requires — useful as a reference when implementing the contracts against a real database.
---
## @ttoss/auth-core(Auth-core)
## Modules
- [AmazonCognito](AmazonCognito/index.md)
- [index](index/index.md)
- [Oidc](Oidc/index.md)
---
## Class: OAuthAuthCode
Defined in: [packages/auth-postgresdb/src/models/OAuthAuthCode.ts:15](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthAuthCode.ts#L15)
A short-lived authorization code with its bound PKCE challenge.
The primary key is the code's SHA-256 hash, never the code itself: a code
travels through a browser redirect and a client's URL bar, so storing it in
plaintext would make a database dump yield replayable codes.
## Extends
- `Model`
## Constructors
### Constructor
> **new OAuthAuthCode**(`values?`, `options?`): `OAuthAuthCode`
Defined in: node\_modules/.pnpm/sequelize-typescript@2.1.6\_@types+node@26.1.1\_@types+validator@13.15.10\_reflect-metadat\_4b56ff65ccbbb483836c71bec8c3693e/node\_modules/sequelize-typescript/dist/model/model/model.d.ts:21
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `values?` | `Optional`\<`any`, `string`\> |
| `options?` | `BuildOptions` |
#### Returns
`OAuthAuthCode`
#### Inherited from
`Model.constructor`
## Properties
### clientId
> **clientId**: `string`
Defined in: [packages/auth-postgresdb/src/models/OAuthAuthCode.ts:29](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthAuthCode.ts#L29)
The `client_id` the code was issued to.
***
### codeChallenge
> **codeChallenge**: `string`
Defined in: [packages/auth-postgresdb/src/models/OAuthAuthCode.ts:43](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthAuthCode.ts#L43)
The PKCE `code_challenge` (S256) bound to this code.
***
### codeHash
> **codeHash**: `string`
Defined in: [packages/auth-postgresdb/src/models/OAuthAuthCode.ts:22](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthAuthCode.ts#L22)
SHA-256 hash (hex) of the authorization code.
***
### expiresAt
> **expiresAt**: `Date`
Defined in: [packages/auth-postgresdb/src/models/OAuthAuthCode.ts:64](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthAuthCode.ts#L64)
Instant after which the code is invalid.
***
### redirectUri
> **redirectUri**: `string`
Defined in: [packages/auth-postgresdb/src/models/OAuthAuthCode.ts:36](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthAuthCode.ts#L36)
The redirect URI the code was issued for (must match on exchange).
***
### scopes
> **scopes**: `string`[]
Defined in: [packages/auth-postgresdb/src/models/OAuthAuthCode.ts:50](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthAuthCode.ts#L50)
The scopes granted to this code.
***
### subject
> **subject**: `string`
Defined in: [packages/auth-postgresdb/src/models/OAuthAuthCode.ts:57](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthAuthCode.ts#L57)
The authenticated end-user subject identifier.
---
## Class: OAuthClient
Defined in: [packages/auth-postgresdb/src/models/OAuthClient.ts:14](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthClient.ts#L14)
A registered OAuth client (RFC 7591 dynamic client registration).
The RFC's registered fields get their own columns so they can be queried and
indexed; any additional metadata a client submits is kept verbatim in
`metadata`, because `OAuthClientMetadata` is an open shape.
## Extends
- `Model`
## Constructors
### Constructor
> **new OAuthClient**(`values?`, `options?`): `OAuthClient`
Defined in: node\_modules/.pnpm/sequelize-typescript@2.1.6\_@types+node@26.1.1\_@types+validator@13.15.10\_reflect-metadat\_4b56ff65ccbbb483836c71bec8c3693e/node\_modules/sequelize-typescript/dist/model/model/model.d.ts:21
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `values?` | `Optional`\<`any`, `string`\> |
| `options?` | `BuildOptions` |
#### Returns
`OAuthClient`
#### Inherited from
`Model.constructor`
## Properties
### clientId
> **clientId**: `string`
Defined in: [packages/auth-postgresdb/src/models/OAuthClient.ts:21](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthClient.ts#L21)
The `client_id` issued by the authorization server.
***
### clientIdIssuedAt
> **clientIdIssuedAt**: `number` \| `null`
Defined in: [packages/auth-postgresdb/src/models/OAuthClient.ts:84](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthClient.ts#L84)
Unix timestamp (seconds) when the client was registered.
***
### clientName
> **clientName**: `string` \| `null`
Defined in: [packages/auth-postgresdb/src/models/OAuthClient.ts:42](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthClient.ts#L42)
Human-readable client name shown on consent screens.
***
### clientSecretHash
> **clientSecretHash**: `string` \| `null`
Defined in: [packages/auth-postgresdb/src/models/OAuthClient.ts:35](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthClient.ts#L35)
SHA-256 hash (hex) of the client secret for confidential clients, `null`
for public clients (`token_endpoint_auth_method: 'none'`).
The secret itself is never stored: the token endpoint only ever compares a
presented value, so a hash is enough and a database dump yields nothing
replayable.
***
### grantTypes
> **grantTypes**: `string`[] \| `null`
Defined in: [packages/auth-postgresdb/src/models/OAuthClient.ts:56](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthClient.ts#L56)
OAuth grant types the client may use.
***
### metadata
> **metadata**: `Record`\<`string`, `unknown`\>
Defined in: [packages/auth-postgresdb/src/models/OAuthClient.ts:95](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthClient.ts#L95)
Registration metadata outside the columns above, preserved so a client's
submitted document round-trips unchanged (e.g. `logo_uri`, `client_uri`).
***
### redirectUris
> **redirectUris**: `string`[]
Defined in: [packages/auth-postgresdb/src/models/OAuthClient.ts:49](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthClient.ts#L49)
Exact redirect URIs registered for this client.
***
### responseTypes
> **responseTypes**: `string`[] \| `null`
Defined in: [packages/auth-postgresdb/src/models/OAuthClient.ts:63](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthClient.ts#L63)
OAuth response types the client may use.
***
### scope
> **scope**: `string` \| `null`
Defined in: [packages/auth-postgresdb/src/models/OAuthClient.ts:77](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthClient.ts#L77)
Space-separated scopes the client may request.
***
### tokenEndpointAuthMethod
> **tokenEndpointAuthMethod**: `string` \| `null`
Defined in: [packages/auth-postgresdb/src/models/OAuthClient.ts:70](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthClient.ts#L70)
Client authentication method at the token endpoint.
---
## Class: OAuthConsent
Defined in: [packages/auth-postgresdb/src/models/OAuthConsent.ts:16](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthConsent.ts#L16)
A single-use consent handoff, correlated by the PKCE `code_challenge`.
This is the record an external consent screen writes on approval so the
restarted `/authorize` request can be approved without asking again — it is
not a durable "user X trusts client Y" grant, which is an app-level
authorization decision and belongs in the app's own schema.
## Extends
- `Model`
## Constructors
### Constructor
> **new OAuthConsent**(`values?`, `options?`): `OAuthConsent`
Defined in: node\_modules/.pnpm/sequelize-typescript@2.1.6\_@types+node@26.1.1\_@types+validator@13.15.10\_reflect-metadat\_4b56ff65ccbbb483836c71bec8c3693e/node\_modules/sequelize-typescript/dist/model/model/model.d.ts:21
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `values?` | `Optional`\<`any`, `string`\> |
| `options?` | `BuildOptions` |
#### Returns
`OAuthConsent`
#### Inherited from
`Model.constructor`
## Properties
### codeChallenge
> **codeChallenge**: `string`
Defined in: [packages/auth-postgresdb/src/models/OAuthConsent.ts:23](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthConsent.ts#L23)
The PKCE `code_challenge` the consent was recorded against.
***
### expiresAt
> **expiresAt**: `Date`
Defined in: [packages/auth-postgresdb/src/models/OAuthConsent.ts:44](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthConsent.ts#L44)
Instant after which the consent is no longer usable.
***
### scopes
> **scopes**: `string`[]
Defined in: [packages/auth-postgresdb/src/models/OAuthConsent.ts:37](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthConsent.ts#L37)
The scopes the user approved.
***
### subject
> **subject**: `string`
Defined in: [packages/auth-postgresdb/src/models/OAuthConsent.ts:30](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthConsent.ts#L30)
The authenticated end-user subject identifier.
---
## Class: OAuthRefreshToken
Defined in: [packages/auth-postgresdb/src/models/OAuthRefreshToken.ts:17](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthRefreshToken.ts#L17)
A refresh token tracked for OAuth 2.1 rotation, stored by hash so a database
dump yields no usable credentials.
`consumedAt` marks a rotated token. Presenting one again is reuse, and
`createRefreshRotation` revokes the whole `(clientId, subject)` token set —
which is why the store adapter must report a live token's `consumedAt` as
absent rather than as `null`.
## Extends
- `Model`
## Constructors
### Constructor
> **new OAuthRefreshToken**(`values?`, `options?`): `OAuthRefreshToken`
Defined in: node\_modules/.pnpm/sequelize-typescript@2.1.6\_@types+node@26.1.1\_@types+validator@13.15.10\_reflect-metadat\_4b56ff65ccbbb483836c71bec8c3693e/node\_modules/sequelize-typescript/dist/model/model/model.d.ts:21
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `values?` | `Optional`\<`any`, `string`\> |
| `options?` | `BuildOptions` |
#### Returns
`OAuthRefreshToken`
#### Inherited from
`Model.constructor`
## Properties
### clientId
> **clientId**: `string`
Defined in: [packages/auth-postgresdb/src/models/OAuthRefreshToken.ts:31](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthRefreshToken.ts#L31)
The `client_id` the token was issued to.
***
### consumedAt
> **consumedAt**: `Date` \| `null`
Defined in: [packages/auth-postgresdb/src/models/OAuthRefreshToken.ts:59](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthRefreshToken.ts#L59)
Instant the token was rotated (consumed), or `null` while it is live.
***
### expiresAt
> **expiresAt**: `Date`
Defined in: [packages/auth-postgresdb/src/models/OAuthRefreshToken.ts:52](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthRefreshToken.ts#L52)
Instant after which the token is invalid.
***
### scopes
> **scopes**: `string`[]
Defined in: [packages/auth-postgresdb/src/models/OAuthRefreshToken.ts:45](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthRefreshToken.ts#L45)
The scopes granted to this token.
***
### subject
> **subject**: `string`
Defined in: [packages/auth-postgresdb/src/models/OAuthRefreshToken.ts:38](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthRefreshToken.ts#L38)
The authenticated end-user subject identifier.
***
### tokenHash
> **tokenHash**: `string`
Defined in: [packages/auth-postgresdb/src/models/OAuthRefreshToken.ts:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/OAuthRefreshToken.ts#L24)
SHA-256 hash (hex) of the opaque refresh token.
---
## Function: createAuthCodeStore()
> **createAuthCodeStore**(`__namedParameters`): `AuthCodeStore`
Defined in: [packages/auth-postgresdb/src/stores/createAuthCodeStore.ts:16](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/stores/createAuthCodeStore.ts#L16)
Creates an AuthCodeStore backed by the `oauth_auth_codes` table,
storing codes by SHA-256 hash.
The engine hands the store the plaintext code on every call and never compares
the returned `code` against anything — it reads only `clientId`,
`redirectUri`, `codeChallenge`, `scopes`, `subject`, and `expiresAt`. So the
adapter hashes to find the row and echoes the presented value back, and a
database dump yields no replayable codes.
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `__namedParameters` | \{ `model`: *typeof* [`OAuthAuthCode`](../classes/OAuthAuthCode.md); \} | - |
| `__namedParameters.model` | *typeof* [`OAuthAuthCode`](../classes/OAuthAuthCode.md) | The `OAuthAuthCode` model class, taken from the app's `db` handle. |
## Returns
`AuthCodeStore`
---
## Function: createClientStore()
> **createClientStore**(`__namedParameters`): `ClientStore`
Defined in: [packages/auth-postgresdb/src/stores/createClientStore.ts:71](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/stores/createClientStore.ts#L71)
Creates a ClientStore backed by the `oauth_clients` table, storing
client secrets by SHA-256 hash.
Because the secret is not recoverable, `get` omits `client_secret` and client
authentication goes through `verifyClientSecret`, which compares the
presented value against the stored hash. The engine only ever needs that
comparison — the registration response echoes the secret from the document it
just generated, never from a read — so nothing is lost by not keeping it.
`register` upserts, so re-registering an existing `client_id` replaces the
stored document rather than failing on the primary key.
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `__namedParameters` | \{ `model`: *typeof* [`OAuthClient`](../classes/OAuthClient.md); \} | - |
| `__namedParameters.model` | *typeof* [`OAuthClient`](../classes/OAuthClient.md) | The `OAuthClient` model class, taken from the app's `db` handle. |
## Returns
`ClientStore`
---
## Function: createConsentStore()
> **createConsentStore**(`__namedParameters`): [`PostgresdbConsentStore`](../interfaces/PostgresdbConsentStore.md)
Defined in: [packages/auth-postgresdb/src/stores/createConsentStore.ts:25](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/stores/createConsentStore.ts#L25)
Creates a consent store backed by the `oauth_consents` table, for use with
`createRedirectConsentOnAuthorize`.
Reads and deletes satisfy `ConsentGrantStore`; `saveConsentGrant` covers the
write the consent page performs. Grants are single-use — the `onAuthorize`
hook deletes each one as it consumes it.
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `__namedParameters` | \{ `model`: *typeof* [`OAuthConsent`](../classes/OAuthConsent.md); \} | - |
| `__namedParameters.model` | *typeof* [`OAuthConsent`](../classes/OAuthConsent.md) | The `OAuthConsent` model class, taken from the app's `db` handle. |
## Returns
[`PostgresdbConsentStore`](../interfaces/PostgresdbConsentStore.md)
---
## Function: createPostgresdbOAuthStores()
> **createPostgresdbOAuthStores**(`__namedParameters`): [`PostgresdbOAuthStores`](../interfaces/PostgresdbOAuthStores.md)
Defined in: [packages/auth-postgresdb/src/createPostgresdbOAuthStores.ts:47](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/createPostgresdbOAuthStores.ts#L47)
Creates every durable OAuth store from a `@ttoss/postgresdb` `db` handle.
The stores are mechanical adapters between the `@ttoss/auth-core` store
contracts and Sequelize, so an app that already uses `@ttoss/postgresdb` does
not have to write them — nor reach around its own ORM to inject a raw `pg`
query runner.
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `__namedParameters` | \{ `db`: \{ `OAuthAuthCode`: *typeof* [`OAuthAuthCode`](../classes/OAuthAuthCode.md); `OAuthClient`: *typeof* [`OAuthClient`](../classes/OAuthClient.md); `OAuthConsent`: *typeof* [`OAuthConsent`](../classes/OAuthConsent.md); `OAuthRefreshToken`: *typeof* [`OAuthRefreshToken`](../classes/OAuthRefreshToken.md); \}; \} | - |
| `__namedParameters.db` | \{ `OAuthAuthCode`: *typeof* [`OAuthAuthCode`](../classes/OAuthAuthCode.md); `OAuthClient`: *typeof* [`OAuthClient`](../classes/OAuthClient.md); `OAuthConsent`: *typeof* [`OAuthConsent`](../classes/OAuthConsent.md); `OAuthRefreshToken`: *typeof* [`OAuthRefreshToken`](../classes/OAuthRefreshToken.md); \} | The handle returned by `@ttoss/postgresdb`'s `initialize`, with `oauthModels` among its registered models. |
| `__namedParameters.db.OAuthAuthCode` | *typeof* [`OAuthAuthCode`](../classes/OAuthAuthCode.md) | - |
| `__namedParameters.db.OAuthClient` | *typeof* [`OAuthClient`](../classes/OAuthClient.md) | - |
| `__namedParameters.db.OAuthConsent` | *typeof* [`OAuthConsent`](../classes/OAuthConsent.md) | - |
| `__namedParameters.db.OAuthRefreshToken` | *typeof* [`OAuthRefreshToken`](../classes/OAuthRefreshToken.md) | - |
## Returns
[`PostgresdbOAuthStores`](../interfaces/PostgresdbOAuthStores.md)
## Example
```typescript
const db = await initialize({ models: { ...oauthModels, User } });
const { clientStore, authCodeStore, consentStore, refreshTokenStore } =
createPostgresdbOAuthStores({ db });
```
---
## Function: createRefreshTokenStore()
> **createRefreshTokenStore**(`__namedParameters`): `RefreshTokenStore`
Defined in: [packages/auth-postgresdb/src/stores/createRefreshTokenStore.ts:10](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/stores/createRefreshTokenStore.ts#L10)
Creates a RefreshTokenStore backed by the `oauth_refresh_tokens`
table, keyed by token hash and by the `(clientId, subject)` owner that
`deleteByOwner` revokes on reuse detection.
## Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `__namedParameters` | \{ `model`: *typeof* [`OAuthRefreshToken`](../classes/OAuthRefreshToken.md); \} | - |
| `__namedParameters.model` | *typeof* [`OAuthRefreshToken`](../classes/OAuthRefreshToken.md) | The `OAuthRefreshToken` model class, taken from the app's `db` handle. |
## Returns
`RefreshTokenStore`
---
## @ttoss/auth-postgresdb
## Classes
- [OAuthAuthCode](classes/OAuthAuthCode.md)
- [OAuthClient](classes/OAuthClient.md)
- [OAuthConsent](classes/OAuthConsent.md)
- [OAuthRefreshToken](classes/OAuthRefreshToken.md)
## Interfaces
- [PostgresdbConsentStore](interfaces/PostgresdbConsentStore.md)
- [PostgresdbOAuthStores](interfaces/PostgresdbOAuthStores.md)
## Type Aliases
- [OAuthModels](type-aliases/OAuthModels.md)
## Variables
- [oauthModels](variables/oauthModels.md)
## Functions
- [createAuthCodeStore](functions/createAuthCodeStore.md)
- [createClientStore](functions/createClientStore.md)
- [createConsentStore](functions/createConsentStore.md)
- [createPostgresdbOAuthStores](functions/createPostgresdbOAuthStores.md)
- [createRefreshTokenStore](functions/createRefreshTokenStore.md)
---
## @ttoss/auth-postgresdb(Auth-postgresdb)
Durable Postgres persistence for the OAuth 2.1 authorization server in [`@ttoss/auth-core`](https://ttoss.dev/docs/modules/packages/auth-core): the Sequelize models for the RFC data model, plus the store adapters `createOAuthHandlers`, `createRefreshRotation`, and `createRedirectConsentOnAuthorize` expect.
`@ttoss/auth-core` ships `Map`-backed stores for tests and local development; this package is what production swaps in behind the same interfaces, without reaching around your ORM to inject a raw `pg` query runner.
## Installation
```bash
pnpm add @ttoss/auth-postgresdb @ttoss/auth-core @ttoss/postgresdb
```
## Usage
Register `oauthModels` alongside your own models so `ttoss-postgresdb sync` and `erd` manage these tables like any other, then build the stores from the `db` handle:
```typescript
createPostgresdbOAuthStores,
oauthModels,
} from '@ttoss/auth-postgresdb';
export const db = await initialize({ models: { ...oauthModels, User } });
export const { clientStore, authCodeStore, consentStore, refreshTokenStore } =
createPostgresdbOAuthStores({ db });
```
The stores drop straight into the OAuth server:
```typescript
const refresh = createRefreshRotation({ store: refreshTokenStore });
const authServer = oauthServer({
issuer: 'https://api.example.com',
clientStore,
authCodeStore,
onRefreshToken: refresh.onRefreshToken,
// …issueTokens, onAuthorize…
});
```
Each store is also exported on its own (`createClientStore`, `createAuthCodeStore`, `createConsentStore`, `createRefreshTokenStore`) for apps that register only some of the models.
## Schema
| Model | Table | Primary key |
| ------------------- | ---------------------- | ---------------- |
| `OAuthClient` | `oauth_clients` | `client_id` |
| `OAuthAuthCode` | `oauth_auth_codes` | `code_hash` |
| `OAuthConsent` | `oauth_consents` | `code_challenge` |
| `OAuthRefreshToken` | `oauth_refresh_tokens` | `token_hash` |
Every credential — authorization codes (`code_hash`), refresh tokens (`token_hash`), and client secrets (`client_secret_hash`) — is stored by SHA-256 hash, never in plaintext, so a database dump yields nothing replayable. `OAuthClient` keeps the registered RFC 7591 fields in their own columns and any additional submitted metadata in a `metadata` JSONB column, so a registration document round-trips unchanged.
## Three traps these adapters absorb
**Authorization codes are hashed at rest.** `AuthCodeStore.get` is handed the plaintext code, but a code travels through a browser redirect and a client's URL bar. The engine never compares the returned `code` against anything — it reads only `clientId`, `redirectUri`, `codeChallenge`, `scopes`, `subject`, and `expiresAt` — so the adapter hashes to find the row and echoes the presented value back.
**Client secrets are hashed at rest too, which takes a different mechanism.** A secret _is_ compared, so the adapter cannot simply hash the row away and echo the presented value back. Instead `clientStore` implements `ClientStore.verifyClientSecret`: the engine hands over the presented secret and the store compares it against the stored hash in constant time, so the raw value never has to be recoverable. Consequently `get` omits `client_secret` from the document it returns — nothing in the engine needs it, since the registration response echoes the secret from the document it just generated rather than from a read.
Implementing `verifyClientSecret` is what makes hashing possible at all. A store that omits it falls back to the engine comparing the `client_secret` returned by `get`, which forces the store to keep the secret recoverable — plaintext, or encrypted with a key the app has to manage.
**A live refresh token reports no `consumedAt` at all.** `createRefreshRotation` treats `stored.consumedAt !== undefined` as reuse. A nullable timestamp column reads back as `null`, which is `!== undefined`, so a naive adapter makes every live token look consumed: the first refresh is treated as a replay and revokes the owner's entire token set — "refresh works once, then the client must re-authorize forever". The adapter omits the key instead of setting it to `null`.
## Consent
`consentStore` satisfies the `ConsentGrantStore` that `createRedirectConsentOnAuthorize` consumes, and adds `saveConsentGrant` for the write your consent page performs on approval. It is the single-use handoff keyed by the PKCE `code_challenge` — not a durable "user X trusts client Y" record, which is an app-level authorization decision and belongs in your own schema.
## Related
- [OAuth Authorization Server](https://ttoss.dev/docs/engineering/guidelines/oauth-authorization-server) — the full server setup and the ttoss-vs-app responsibility split
- [MCP Server with OAuth](https://ttoss.dev/docs/engineering/guidelines/mcp-server-oauth) — the MCP application of these primitives
- [`@ttoss/postgresdb`](https://ttoss.dev/docs/modules/packages/postgresdb) — `initialize`, and the `sync` / `erd` CLI
---
## Interface: PostgresdbConsentStore
Defined in: [packages/auth-postgresdb/src/stores/createConsentStore.ts:6](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/stores/createConsentStore.ts#L6)
A ConsentGrantStore plus the write side an app's consent page needs.
## Extends
- `ConsentGrantStore`
## Properties
### deleteConsentGrant
> **deleteConsentGrant**: (`params`) => `Promise`\<`void`\>
Defined in: [packages/auth-core/src/redirectConsentOnAuthorize.ts:32](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/redirectConsentOnAuthorize.ts#L32)
Delete a consent grant (called after consumption to enforce single-use).
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `params` | \{ `codeChallenge`: `string`; \} |
| `params.codeChallenge` | `string` |
#### Returns
`Promise`\<`void`\>
#### Inherited from
`ConsentGrantStore.deleteConsentGrant`
***
### getConsentGrant
> **getConsentGrant**: (`params`) => `Promise`\<`ConsentGrant` \| `undefined`\>
Defined in: [packages/auth-core/src/redirectConsentOnAuthorize.ts:28](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-core/src/redirectConsentOnAuthorize.ts#L28)
Look up a consent grant by its PKCE `codeChallenge`.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `params` | \{ `codeChallenge`: `string`; \} |
| `params.codeChallenge` | `string` |
#### Returns
`Promise`\<`ConsentGrant` \| `undefined`\>
#### Inherited from
`ConsentGrantStore.getConsentGrant`
***
### saveConsentGrant
> **saveConsentGrant**: (`grant`) => `Promise`\<`void`\>
Defined in: [packages/auth-postgresdb/src/stores/createConsentStore.ts:12](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/stores/createConsentStore.ts#L12)
Record an approval so the restarted `/authorize` request can consume it.
Call this from the consent page's approve handler, before navigating back
to the authorization server's `/authorize`.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `grant` | `ConsentGrant` & `object` |
#### Returns
`Promise`\<`void`\>
---
## Interface: PostgresdbOAuthStores
Defined in: [packages/auth-postgresdb/src/createPostgresdbOAuthStores.ts:17](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/createPostgresdbOAuthStores.ts#L17)
The durable OAuth stores returned by [createPostgresdbOAuthStores](../functions/createPostgresdbOAuthStores.md).
## Properties
### authCodeStore
> **authCodeStore**: `AuthCodeStore`
Defined in: [packages/auth-postgresdb/src/createPostgresdbOAuthStores.ts:21](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/createPostgresdbOAuthStores.ts#L21)
Single-use authorization codes, stored by hash.
***
### clientStore
> **clientStore**: `ClientStore`
Defined in: [packages/auth-postgresdb/src/createPostgresdbOAuthStores.ts:19](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/createPostgresdbOAuthStores.ts#L19)
Dynamic client registrations, for `createOAuthHandlers`.
***
### consentStore
> **consentStore**: [`PostgresdbConsentStore`](PostgresdbConsentStore.md)
Defined in: [packages/auth-postgresdb/src/createPostgresdbOAuthStores.ts:23](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/createPostgresdbOAuthStores.ts#L23)
Consent handoff records for `createRedirectConsentOnAuthorize`.
***
### refreshTokenStore
> **refreshTokenStore**: `RefreshTokenStore`
Defined in: [packages/auth-postgresdb/src/createPostgresdbOAuthStores.ts:25](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/createPostgresdbOAuthStores.ts#L25)
Tracked refresh tokens, for `createRefreshRotation`.
---
## Type Alias: OAuthModels
> **OAuthModels** = *typeof* [`oauthModels`](../variables/oauthModels.md)
Defined in: [packages/auth-postgresdb/src/models/index.ts:27](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/index.ts#L27)
The shape a `db` handle must have to back the OAuth stores.
---
## Variable: oauthModels
> `const` **oauthModels**: `object`
Defined in: [packages/auth-postgresdb/src/models/index.ts:19](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/auth-postgresdb/src/models/index.ts#L19)
The OAuth data model, ready to register alongside the application's own
models so `ttoss-postgresdb sync` and `erd` cover these tables like any
other instead of them being a side-channel schema the CLI cannot see.
## Type Declaration
### OAuthAuthCode
> **OAuthAuthCode**: *typeof* [`OAuthAuthCode`](../classes/OAuthAuthCode.md)
### OAuthClient
> **OAuthClient**: *typeof* [`OAuthClient`](../classes/OAuthClient.md)
### OAuthConsent
> **OAuthConsent**: *typeof* [`OAuthConsent`](../classes/OAuthConsent.md)
### OAuthRefreshToken
> **OAuthRefreshToken**: *typeof* [`OAuthRefreshToken`](../classes/OAuthRefreshToken.md)
## Example
```typescript
export const db = await initialize({ models: { ...oauthModels, User } });
```
---
## @ttoss/aws-appsync-nodejs
## Type Aliases
- [Config](type-aliases/Config.md)
- [Query](type-aliases/Query.md)
## Variables
- [appSyncClient](variables/appSyncClient.md)
---
## @ttoss/aws-appsync-nodejs(Aws-appsync-nodejs)
This package implements a AWS AppSync client for Node.js. We've followed the [AWS Amplify](https://docs.amplify.aws/lib/graphqlapi/graphql-from-nodejs/q/platform/js/) example to create this package.
## Installation
```bash
pnpm add @ttoss/aws-appsync-nodejs
```
## Quickstart
```typescript
appSyncClient.setConfig({
endpoint: 'https://xxxxxx.appsync-api.us-east-1.amazonaws.com/graphql',
apiKey: 'da2-xxxxxxxxxxxxxxxxxxxxxxxxxx',
});
const query = /* GraphQL */ `
query user($id: ID!) {
user(id: $id) {
id
name
}
}
`;
appSyncClient.query(query, { id: '1' }).then((result) => {
console.log(result);
});
```
## Config
You need to configure the client with `endpoint` (required), `apiKey` (optional) and `credentials` (optional).
1. If you don't provide `apiKey` or `credentials`, the client will try to use the AWS credentials from the environment variables of your system—local computer, AWS Lambda, EC2.
```typescript
appSyncClient.setConfig({
endpoint: 'https://xxxxxx.appsync-api.us-east-1.amazonaws.com/graphql',
});
```
2. If you provide `apiKey`, the client will use the API key to authenticate.
```typescript
appSyncClient.setConfig({
endpoint: 'https://xxxxxx.appsync-api.us-east-1.amazonaws.com/graphql',
apiKey: 'da2-xxxxxxxxxxxxxxxxxxxxxxxxxx',
});
```
3. If you provide `credentials`, the client will use the credentials to authenticate.
```typescript
appSyncClient.setConfig({
endpoint,
credentials: {
accessKeyId: // access key id,
secretAccessKey: // secret access key,
sessionToken: // optional session token,
},
});
```
If you provide the default endpoint (`https://xxxxxx.appsync-api.us-east-1.amazonaws.com/graphql`), the client will retrieve the region from the endpoint. If you provide the endpoint with the custom domain (`https://custom-domain.com`), you need to provide the region as well.
```typescript
appSyncClient.setConfig({
endpoint: 'https://custom-domain.com',
region: 'us-east-1',
credentials: {
accessKeyId: // access key id,
secretAccessKey: // secret access key,
sessionToken: // optional session token,
},
});
```
## Triggering subscriptions from the backend
Use `appSyncClient.mutate()` to execute a GraphQL mutation that triggers an AppSync subscription. This is the recommended way to push real-time events to connected clients from a backend Lambda or service.
```typescript
appSyncClient.setConfig({
endpoint: process.env.APPSYNC_ENDPOINT!,
});
await appSyncClient.mutate(
/* GraphQL */ `
mutation SendMessage($content: String!, $author: String!) {
sendMessage(content: $content, author: $author) {
content
author
}
}
`,
{ content: 'Hello!', author: 'Alice' }
);
```
`mutate` uses the same authentication and transport as `query` — whichever auth mode is configured (`apiKey`, `credentials`, or the default provider) is applied automatically.
> See the `@ttoss/appsync-api` documentation for how to set up a subscription with a NONE data-source resolver on the AppSync side.
---
## Type Alias: Config
> **Config** = `object`
Defined in: [index.ts:11](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/aws-appsync-nodejs/src/index.ts#L11)
## Properties
### apiKey?
> `optional` **apiKey?**: `string`
Defined in: [index.ts:14](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/aws-appsync-nodejs/src/index.ts#L14)
***
### credentials?
> `optional` **credentials?**: `AwsCredentialIdentity`
Defined in: [index.ts:15](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/aws-appsync-nodejs/src/index.ts#L15)
***
### endpoint
> **endpoint**: `string`
Defined in: [index.ts:12](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/aws-appsync-nodejs/src/index.ts#L12)
***
### region?
> `optional` **region?**: `string`
Defined in: [index.ts:13](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/aws-appsync-nodejs/src/index.ts#L13)
---
## Type Alias: Query
> **Query** = (`query`, `variables?`) => `Promise`\<\{ `data`: `Record`\<`string`, `unknown`\> \| `null`; `errors?`: `object`[]; \}\>
Defined in: [index.ts:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/aws-appsync-nodejs/src/index.ts#L24)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `query` | `string` |
| `variables?` | `Record`\<`string`, `unknown`\> |
## Returns
`Promise`\<\{ `data`: `Record`\<`string`, `unknown`\> \| `null`; `errors?`: `object`[]; \}\>
---
## Variable: appSyncClient
> `const` **appSyncClient**: `object`
Defined in: [index.ts:114](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/aws-appsync-nodejs/src/index.ts#L114)
## Type Declaration
### mutate
> **mutate**: [`Query`](../type-aliases/Query.md) = `query`
Execute a GraphQL mutation against the configured AppSync endpoint.
Behaves identically to [query](#query) — AppSync determines the operation
type from the document itself, so this alias exists only to make the
caller's intent explicit (e.g. triggering a subscription).
### query
> **query**: [`Query`](../type-aliases/Query.md)
Execute a GraphQL query against the configured AppSync endpoint.
### setConfig
> **setConfig**: (`config`) => `void`
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `config` | [`Config`](../type-aliases/Config.md) |
#### Returns
`void`
### config
#### Get Signature
> **get** **config**(): [`Config`](../type-aliases/Config.md)
##### Returns
[`Config`](../type-aliases/Config.md)
---
## Function: cli()
> **cli**(): `Argv`\<`Omit`\<\{ \}, `"branch"` \| `"config"` \| `"environment"` \| `"environments"` \| `"project"` \| `"region"`\> & `InferredOptionTypes`\<\{ `branch`: \{ `coerce`: (`value`) => `any`; `require`: `false`; `type`: `"string"`; \}; `config`: \{ `alias`: `"c"`; `describe`: `"Path to config file. You can create a config file and set all options there. Valid extensions: .js, .json, .ts, .yml, or .yaml."`; `require`: `false`; `type`: `"string"`; \}; `environment`: \{ `alias`: readonly \[`"e"`, `"env"`\]; `coerce`: (`value`) => `any`; `type`: `"string"`; \}; `environments`: \{ \}; `project`: \{ `coerce`: (`value`) => `any`; `require`: `false`; `type`: `"string"`; \}; `region`: \{ `alias`: `"r"`; `default`: `"us-east-1"`; `describe`: `"AWS region."`; `type`: `"string"`; \}; \}\>\>
Defined in: [cli.ts:210](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/cli.ts#L210)
Transformed to method because finalConfig was failing the tests because as
function we encapsulate the logic and it is not executed on the import.
## Returns
`Argv`\<`Omit`\<\{ \}, `"branch"` \| `"config"` \| `"environment"` \| `"environments"` \| `"project"` \| `"region"`\> & `InferredOptionTypes`\<\{ `branch`: \{ `coerce`: (`value`) => `any`; `require`: `false`; `type`: `"string"`; \}; `config`: \{ `alias`: `"c"`; `describe`: `"Path to config file. You can create a config file and set all options there. Valid extensions: .js, .json, .ts, .yml, or .yaml."`; `require`: `false`; `type`: `"string"`; \}; `environment`: \{ `alias`: readonly \[`"e"`, `"env"`\]; `coerce`: (`value`) => `any`; `type`: `"string"`; \}; `environments`: \{ \}; `project`: \{ `coerce`: (`value`) => `any`; `require`: `false`; `type`: `"string"`; \}; `region`: \{ `alias`: `"r"`; `default`: `"us-east-1"`; `describe`: `"AWS region."`; `type`: `"string"`; \}; \}\>\>
---
## Function: getConfigFileOptions()
> **getConfigFileOptions**(`__namedParameters?`): `object`
Defined in: [cli.ts:116](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/cli.ts#L116)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | \{ `args?`: `string`[]; \} |
| `__namedParameters.args?` | `string`[] |
## Returns
`object`
### branch
> **branch**: `string` \| `undefined`
### environment
> **environment**: `string` \| `undefined`
### project
> **project**: `string` \| `undefined`
---
## Function: loadDotEnv()
> **loadDotEnv**(): `void`
Defined in: [cli.ts:180](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/cli.ts#L180)
Load the appropriate .env file. If an environment is specified (e.g. `-e
Production`) and a `.env.Production` file exists, load only that file so
environment-specific values are authoritative and nothing from a generic
`.env` can bleed through. Fall back to `.env` when no environment-specific
file is found or when no environment is specified.
## Returns
`void`
---
## cli
## Variables
- [options](variables/options.md)
## Functions
- [cli](functions/cli.md)
- [getConfigFileOptions](functions/getConfigFileOptions.md)
- [loadDotEnv](functions/loadDotEnv.md)
---
## Variable: options
> `const` **options**: `object`
Defined in: [cli.ts:29](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/cli.ts#L29)
## Type Declaration
### branch
> `readonly` **branch**: `object`
#### branch.coerce
> `readonly` **coerce**: (`value`) => `any`
##### Parameters
| Parameter | Type |
| ------ | ------ |
| `value` | `any` |
##### Returns
`any`
#### branch.require
> `readonly` **require**: `false` = `false`
#### branch.type
> `readonly` **type**: `"string"` = `'string'`
### config
> `readonly` **config**: `object`
#### config.alias
> `readonly` **alias**: `"c"` = `'c'`
#### config.describe
> `readonly` **describe**: `"Path to config file. You can create a config file and set all options there. Valid extensions: .js, .json, .ts, .yml, or .yaml."` = `'Path to config file. You can create a config file and set all options there. Valid extensions: .js, .json, .ts, .yml, or .yaml.'`
#### config.require
> `readonly` **require**: `false` = `false`
#### config.type
> `readonly` **type**: `"string"` = `'string'`
### environment
> `readonly` **environment**: `object`
#### environment.alias
> `readonly` **alias**: readonly \[`"e"`, `"env"`\]
#### environment.coerce
> `readonly` **coerce**: (`value`) => `any`
##### Parameters
| Parameter | Type |
| ------ | ------ |
| `value` | `any` |
##### Returns
`any`
#### environment.type
> `readonly` **type**: `"string"` = `'string'`
### environments
> `readonly` **environments**: `object` = `{}`
### project
> `readonly` **project**: `object`
#### project.coerce
> `readonly` **coerce**: (`value`) => `any`
##### Parameters
| Parameter | Type |
| ------ | ------ |
| `value` | `any` |
##### Returns
`any`
#### project.require
> `readonly` **require**: `false` = `false`
#### project.type
> `readonly` **type**: `"string"` = `'string'`
### region
> `readonly` **region**: `object`
#### region.alias
> `readonly` **alias**: `"r"` = `'r'`
#### region.default
> `readonly` **default**: `"us-east-1"` = `AWS_DEFAULT_REGION`
#### region.describe
> `readonly` **describe**: `"AWS region."` = `'AWS region.'`
#### region.type
> `readonly` **type**: `"string"` = `'string'`
---
## config
## Variables
- [AWS\_DEFAULT\_REGION](variables/AWS_DEFAULT_REGION.md)
- [CLOUDFRONT\_REGION](variables/CLOUDFRONT_REGION.md)
- [DEFAULT\_NODE\_RUNTIME](variables/DEFAULT_NODE_RUNTIME.md)
- [DEFAULT\_NODE\_VERSION](variables/DEFAULT_NODE_VERSION.md)
- [NAME](variables/NAME.md)
---
## Variable: AWS\_DEFAULT\_REGION
> `const` **AWS\_DEFAULT\_REGION**: `"us-east-1"` = `'us-east-1'`
Defined in: [config.ts:3](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/config.ts#L3)
---
## Variable: CLOUDFRONT\_REGION
> `const` **CLOUDFRONT\_REGION**: `"us-east-1"` = `'us-east-1'`
Defined in: [config.ts:9](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/config.ts#L9)
CloudFront triggers can be only in US East (N. Virginia) Region.
https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/lambda-requirements-limits.html#lambda-requirements-cloudfront-triggers
---
## Variable: DEFAULT\_NODE\_RUNTIME
> `const` **DEFAULT\_NODE\_RUNTIME**: `"nodejs24.x"`
Defined in: [config.ts:21](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/config.ts#L21)
Default Node.js runtime string.
---
## Variable: DEFAULT\_NODE\_VERSION
> `const` **DEFAULT\_NODE\_VERSION**: `"24"` = `'24'`
Defined in: [config.ts:16](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/config.ts#L16)
Default Node.js version used by CodeBuild runtimes.
https://docs.aws.amazon.com/codebuild/latest/userguide/available-runtimes.html#linux-runtimes
On Carlin, it's used to configure the runtime for the Lambda Layer Builder.
---
## Variable: NAME
> `const` **NAME**: `"carlin"` = `'carlin'`
Defined in: [config.ts:1](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/config.ts#L1)
---
## Function: defineConfig()
## Call Signature
> **defineConfig**\<`Config`\>(`config`): `Config`
Defined in: [defineConfig.ts:183](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L183)
### Type Parameters
| Type Parameter |
| ------ |
| `Config` *extends* [`CarlinConfig`](../type-aliases/CarlinConfig.md) |
### Parameters
| Parameter | Type |
| ------ | ------ |
| `config` | `Config` |
### Returns
`Config`
## Call Signature
> **defineConfig**\<`Config`\>(`config`): [`CarlinConfigFactory`](../type-aliases/CarlinConfigFactory.md)\<`Config`\>
Defined in: [defineConfig.ts:186](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L186)
### Type Parameters
| Type Parameter |
| ------ |
| `Config` *extends* [`CarlinConfig`](../type-aliases/CarlinConfig.md) |
### Parameters
| Parameter | Type |
| ------ | ------ |
| `config` | [`CarlinConfigFactory`](../type-aliases/CarlinConfigFactory.md)\<`Config`\> |
### Returns
[`CarlinConfigFactory`](../type-aliases/CarlinConfigFactory.md)\<`Config`\>
---
## Function: requiredEnv()
> **requiredEnv**(`__namedParameters`): `string`
Defined in: [defineConfig.ts:209](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L209)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | [`RequiredEnvOptions`](../type-aliases/RequiredEnvOptions.md) |
## Returns
`string`
---
## defineConfig
## References
### CarlinConfig
Re-exports [CarlinConfig](type-aliases/CarlinConfig.md)
***
### CarlinConfigContext
Re-exports [CarlinConfigContext](type-aliases/CarlinConfigContext.md)
***
### CarlinConfigFactory
Re-exports [CarlinConfigFactory](type-aliases/CarlinConfigFactory.md)
***
### CarlinParameter
Re-exports [CarlinParameter](type-aliases/CarlinParameter.md)
***
### CarlinParameters
Re-exports [CarlinParameters](type-aliases/CarlinParameters.md)
***
### CarlinParameterValue
Re-exports [CarlinParameterValue](type-aliases/CarlinParameterValue.md)
***
### defineConfig
Re-exports [defineConfig](functions/defineConfig.md)
***
### requiredEnv
Re-exports [requiredEnv](functions/requiredEnv.md)
***
### RequiredEnvOptions
Re-exports [RequiredEnvOptions](type-aliases/RequiredEnvOptions.md)
---
## defineConfig(DefineConfig)
## Type Aliases
- [CarlinConfig](type-aliases/CarlinConfig.md)
- [CarlinConfigContext](type-aliases/CarlinConfigContext.md)
- [CarlinConfigFactory](type-aliases/CarlinConfigFactory.md)
- [CarlinParameter](type-aliases/CarlinParameter.md)
- [CarlinParameters](type-aliases/CarlinParameters.md)
- [CarlinParameterValue](type-aliases/CarlinParameterValue.md)
- [RequiredEnvOptions](type-aliases/RequiredEnvOptions.md)
## Functions
- [defineConfig](functions/defineConfig.md)
- [requiredEnv](functions/requiredEnv.md)
---
## Type Alias: CarlinConfig
> **CarlinConfig** = `object`
Defined in: [defineConfig.ts:20](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L20)
## Indexable
> \[`key`: `string`\]: `unknown`
## Properties
### environments?
> `optional` **environments?**: `Record`\<`string`, `CarlinConfig`\>
Defined in: [defineConfig.ts:22](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L22)
***
### parameters?
> `optional` **parameters?**: [`CarlinParameters`](CarlinParameters.md)
Defined in: [defineConfig.ts:21](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L21)
---
## Type Alias: CarlinConfigContext
> **CarlinConfigContext** = `object`
Defined in: [defineConfig.ts:14](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L14)
## Properties
### branch?
> `optional` **branch?**: `string`
Defined in: [defineConfig.ts:15](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L15)
***
### environment?
> `optional` **environment?**: `string`
Defined in: [defineConfig.ts:16](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L16)
***
### project?
> `optional` **project?**: `string`
Defined in: [defineConfig.ts:17](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L17)
---
## Type Alias: CarlinConfigFactory\
> **CarlinConfigFactory**\<`Config`\> = (`context`) => `Config` \| `Promise`\<`Config`\>
Defined in: [defineConfig.ts:26](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L26)
## Type Parameters
| Type Parameter | Default type |
| ------ | ------ |
| `Config` *extends* [`CarlinConfig`](CarlinConfig.md) | [`CarlinConfig`](CarlinConfig.md) |
## Parameters
| Parameter | Type |
| ------ | ------ |
| `context` | [`CarlinConfigContext`](CarlinConfigContext.md) |
## Returns
`Config` \| `Promise`\<`Config`\>
---
## Type Alias: CarlinParameter
> **CarlinParameter** = `object`
Defined in: [defineConfig.ts:3](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L3)
## Properties
### key
> **key**: `string`
Defined in: [defineConfig.ts:4](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L4)
***
### resolvedValue?
> `optional` **resolvedValue?**: `string`
Defined in: [defineConfig.ts:7](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L7)
***
### usePreviousValue?
> `optional` **usePreviousValue?**: `boolean`
Defined in: [defineConfig.ts:6](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L6)
***
### value?
> `optional` **value?**: `string` \| `number`
Defined in: [defineConfig.ts:5](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L5)
---
## Type Alias: CarlinParameterValue
> **CarlinParameterValue** = `string` \| `number` \| `undefined`
Defined in: [defineConfig.ts:1](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L1)
---
## Type Alias: CarlinParameters
> **CarlinParameters** = [`CarlinParameter`](CarlinParameter.md)[] \| `Record`\<`string`, [`CarlinParameterValue`](CarlinParameterValue.md)\>
Defined in: [defineConfig.ts:10](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L10)
---
## Type Alias: RequiredEnvOptions
> **RequiredEnvOptions** = `object`
Defined in: [defineConfig.ts:30](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L30)
## Properties
### message?
> `optional` **message?**: `string`
Defined in: [defineConfig.ts:32](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L32)
***
### name
> **name**: `string`
Defined in: [defineConfig.ts:31](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/carlin/src/defineConfig.ts#L31)
---
## index(Index)
---
## index(3)
---
## carlin
CLI tool for deploying AWS cloud resources using CloudFormation templates.
```bash
pnpm add -D carlin
```
**[Documentation →](https://ttoss.dev/docs/carlin/)**
## Typed Configuration
Use `defineConfig` from `carlin/config` for typed `carlin.ts` files:
```typescript
export default defineConfig(({ environment }) => {
return {
environment,
parameters: {
DomainName: 'api.example.com',
DatabasePassword: requiredEnv({ name: 'DATABASE_PASSWORD' }),
},
};
});
```
See the [configuration docs](https://ttoss.dev/docs/carlin/core-concepts/configuration) for the full flow from environment variables to CloudFormation parameters.
## License
MIT © [Pedro Arantes](https://twitter.com/arantespp)
---
## carlin(Carlin)
## Modules
- [cli](cli/index.md)
- [config](config/index.md)
- [defineConfig](defineConfig/index.md)
- [defineConfig](defineConfig/index-1.md)
- [index](index/index.md)
- [index](index/index-1.md)
---
## Function: createAuthTemplate()
> **createAuthTemplate**(`params?`): [`CloudFormationTemplate`](../type-aliases/CloudFormationTemplate.md)
Defined in: [cloud-auth/src/template.ts:270](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template.ts#L270)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `params` | `CreateAuthTemplateParams` |
## Returns
[`CloudFormationTemplate`](../type-aliases/CloudFormationTemplate.md)
---
## Function: identityProviderLogicalId()
> **identityProviderLogicalId**(`providerType`): `string`
Defined in: [cloud-auth/src/template-identity-providers.ts:44](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-identity-providers.ts#L44)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `providerType` | [`IdentityProviderType`](../type-aliases/IdentityProviderType.md) |
## Returns
`string`
---
## @ttoss/cloud-auth
## Type Aliases
- [AdditionalAppClientConfig](type-aliases/AdditionalAppClientConfig.md)
- [CloudFormationTemplate](type-aliases/CloudFormationTemplate.md)
- [DomainConfig](type-aliases/DomainConfig.md)
- [IdentityPoolConfig](type-aliases/IdentityPoolConfig.md)
- [IdentityProviderConfig](type-aliases/IdentityProviderConfig.md)
- [IdentityProviderType](type-aliases/IdentityProviderType.md)
- [OAuthConfig](type-aliases/OAuthConfig.md)
- [ResourceServerConfig](type-aliases/ResourceServerConfig.md)
- [ResourceServerScope](type-aliases/ResourceServerScope.md)
## Variables
- [defaultPrincipalTags](variables/defaultPrincipalTags.md)
- [DenyStatement](variables/DenyStatement.md)
- [PASSWORD\_MINIMUM\_LENGTH](variables/PASSWORD_MINIMUM_LENGTH.md)
## Functions
- [createAuthTemplate](functions/createAuthTemplate.md)
- [identityProviderLogicalId](functions/identityProviderLogicalId.md)
---
## @ttoss/cloud-auth(Cloud-auth)
AWS Cognito authentication infrastructure as code. Creates user pools, identity pools, and Lambda triggers with CloudFormation.
## Installation
```bash
pnpm add @ttoss/cloud-auth
```
## Quick Start
```typescript
// src/cloudformation.ts
export default createAuthTemplate();
```
## Core Features
### User Pool Configuration
The template creates a secure user pool with email-based authentication by default:
```typescript
const template = createAuthTemplate({
autoVerifiedAttributes: ['email'], // Default
usernameAttributes: ['email'], // Default
deletionProtection: 'ACTIVE', // Optional: ACTIVE | INACTIVE
schema: [
{
attributeDataType: 'String',
name: 'department',
required: false,
mutable: true,
stringAttributeConstraints: {
maxLength: '100',
minLength: '1',
},
},
],
});
```
### Lambda Triggers
Customize authentication workflows with [AWS Cognito Lambda triggers](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-working-with-lambda-triggers.html). Lambda triggers accept either string ARNs or `Fn::GetAtt` CloudFormation references.
#### Basic Lambda Trigger Setup
```typescript
const template = createAuthTemplate({
lambdaTriggers: {
preSignUp: 'arn:aws:lambda:us-east-1:123456789:function:PreSignUp',
postConfirmation: { 'Fn::GetAtt': ['PostConfirmationFunction', 'Arn'] },
preTokenGeneration: { 'Fn::GetAtt': ['TokenCustomizerFunction', 'Arn'] },
},
});
```
#### Complete Lambda Integration Example
Here's how to integrate Lambda functions with your auth template:
```typescript
// src/cloudformation.ts
export default () => {
const template = createAuthTemplate({
lambdaTriggers: {
postConfirmation: {
'Fn::GetAtt': ['PostConfirmationLambdaFunction', 'Arn'],
},
},
});
// Add Lambda S3 parameters for Carlin deployment
template.Parameters = {
...template.Parameters,
LambdaS3Bucket: { Type: 'String' },
LambdaS3Key: { Type: 'String' },
LambdaS3ObjectVersion: { Type: 'String' },
};
// Define Lambda function resource
template.Resources = {
...template.Resources,
PostConfirmationLambdaFunction: {
Type: 'AWS::Lambda::Function',
Properties: {
Handler: 'triggers.postConfirmation',
Code: {
S3Bucket: { Ref: 'LambdaS3Bucket' },
S3Key: { Ref: 'LambdaS3Key' },
S3ObjectVersion: { Ref: 'LambdaS3ObjectVersion' },
},
Role: 'arn:aws:iam::account:role/lambda-execution-role',
Runtime: 'nodejs22.x',
},
},
};
return template;
};
```
#### Lambda Function Implementation
Create your trigger functions following AWS Lambda handler patterns:
```typescript
// src/triggers.ts
export const postConfirmation: PostConfirmationTriggerHandler = async (
event
) => {
const email = event.request.userAttributes.email;
// Custom logic: send welcome email, create user profile, etc.
console.log(`New user confirmed: ${email}`);
// Always return the event object
return event;
};
```
#### Available Lambda Triggers
Check [Customizing user pool workflows with Lambda triggers](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-working-with-lambda-triggers.html) for more information.
**Authentication Flow:**
- `preSignUp` - Validate signup data, auto-confirm users
- `postConfirmation` - Execute post-signup actions
- `preAuthentication` - Custom authentication validation
- `postAuthentication` - Track logins, update last seen
**Token Customization:**
- `preTokenGeneration` - Add custom claims, modify token content
**User Migration:**
- `userMigration` - Migrate users from external systems
**Custom Challenges:**
- `defineAuthChallenge` - Define custom authentication flows
- `createAuthChallenge` - Generate custom challenges
- `verifyAuthChallengeResponse` - Validate challenge responses
**Messaging:**
- `customMessage` - Customize email/SMS content
- `customEmailSender` - Third-party email providers
- `customSMSSender` - Third-party SMS providers
#### Deployment with Carlin
When using [Carlin deploy](https://ttoss.dev/docs/carlin/commands/deploy), Lambda functions are automatically built and uploaded to S3. Your `Handler` property should match your file structure:
```
src/
└── triggers.ts # Handler: 'triggers.postConfirmation's
```
The S3 parameters (`LambdaS3Bucket`, `LambdaS3Key`, `LambdaS3ObjectVersion`) are automatically injected by Carlin and referenced in your Lambda function's `Code` property.
### Identity Pool
Enable federated identities for AWS resource access:
```typescript
const template = createAuthTemplate({
identityPool: {
enabled: true,
name: 'MyApp_IdentityPool',
allowUnauthenticatedIdentities: false,
},
});
```
#### Custom IAM Policies
Define specific permissions for authenticated and unauthenticated users:
```typescript
const template = createAuthTemplate({
identityPool: {
enabled: true,
authenticatedPolicies: [
{
PolicyName: 'S3Access',
PolicyDocument: {
Version: '2012-10-17',
Statement: [
{
Effect: 'Allow',
Action: ['s3:GetObject', 's3:PutObject'],
Resource: 'arn:aws:s3:::my-bucket/${aws:PrincipalTag/userId}/*',
},
],
},
},
],
},
});
```
#### Principal Tags for Access Control
Enable [attribute-based access control](https://docs.aws.amazon.com/cognito/latest/developerguide/attributes-for-access-control.html) using JWT claims as IAM principal tags:
```typescript
// Default principal tags
const template = createAuthTemplate({
identityPool: { enabled: true },
// Maps: appClientId → 'aud', userId → 'sub'
});
// Custom principal tags
const template = createAuthTemplate({
identityPool: {
enabled: true,
principalTags: {
department: 'custom:department',
role: 'custom:role',
userId: 'sub',
},
},
});
```
Use principal tags in IAM policies for fine-grained access control:
```json
{
"Effect": "Allow",
"Action": "dynamodb:Query",
"Resource": "arn:aws:dynamodb:*:*:table/UserData",
"Condition": {
"StringEquals": {
"dynamodb:LeadingKeys": "${aws:PrincipalTag/userId}"
}
}
}
```
#### External IAM Roles
Use existing IAM roles instead of creating new ones:
```typescript
const template = createAuthTemplate({
identityPool: {
enabled: true,
authenticatedRoleArn: 'arn:aws:iam::123456789012:role/AuthenticatedRole',
unauthenticatedRoleArn:
'arn:aws:iam::123456789012:role:UnauthenticatedRole',
},
});
```
### Hosted UI Domain
Add a Cognito hosted UI so OAuth clients can redirect users to the login page. Use a Cognito prefix domain or bring your own custom domain with an ACM certificate:
```typescript
// Cognito prefix domain (e.g. https://my-app.auth.us-east-1.amazoncognito.com)
const template = createAuthTemplate({
domain: { domainName: 'my-app' },
});
// Custom domain
const template = createAuthTemplate({
domain: {
domainName: 'auth.example.com',
certificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abc',
},
});
```
Output `CognitoUserPoolDomainUrl` is exported with the full URL.
### Social Sign-In (Google and Facebook)
Add Google and/or Facebook as identity providers on the same user pool. Existing username/password users are unaffected — `COGNITO` stays in the client's `SupportedIdentityProviders`, and the federated providers are appended.
Federated sign-in always goes through the hosted UI, so `domain` is required and `oauth` configures the redirect URLs the app client accepts:
```typescript
const template = createAuthTemplate({
domain: { domainName: 'my-app' },
oauth: {
flows: ['code'],
scopes: ['openid', 'email', 'profile'],
callbackUrls: ['https://app.example.com/'],
logoutUrls: ['https://app.example.com/auth'],
},
identityProviders: [
{
providerType: 'Google',
clientId: '',
clientSecret: '',
},
{
providerType: 'Facebook',
clientId: '',
clientSecret: '',
},
],
});
```
`scopes` and `attributeMapping` are optional and default to:
| Provider | Default scopes | Default attribute mapping |
| ---------- | ---------------------- | ------------------------- |
| `Google` | `openid email profile` | `{ email: 'email' }` |
| `Facebook` | `public_profile,email` | `{ email: 'email' }` |
Each provider creates a `CognitoUserPoolIdentityProvider` resource, and the default app client is given a `DependsOn` for it.
**Account linking is not handled here.** Cognito creates a _separate_ user (with a new `sub`) for a federated sign-in, even when the email matches an existing native user. If your application keys records on the Cognito `sub`, add a `preSignUp` Lambda trigger that calls `AdminLinkProviderForUser` — and only link when the provider reports the email as verified, or the flow becomes an account-takeover path.
### Resource Servers and Custom Scopes
Define resource servers with custom OAuth scopes to gate access to your APIs:
```typescript
const template = createAuthTemplate({
resourceServers: [
{
identifier: 'mcp',
name: 'MCP Server',
scopes: [
{ scopeName: 'access', scopeDescription: 'Access the MCP server' },
],
},
],
});
```
The scope `mcp/access` (format: `/`) can then be required by your API.
### Additional App Clients (OAuth / Confidential Clients)
The default app client (`AppClientId`) is a public client used by Amplify and must not have a secret. Use `additionalAppClients` to create separate confidential OAuth clients — for example, a client for a remote MCP connector:
```typescript
const template = createAuthTemplate({
domain: { domainName: 'my-app' },
resourceServers: [
{
identifier: 'mcp',
name: 'MCP Server',
scopes: [
{ scopeName: 'access', scopeDescription: 'Access the MCP server' },
],
},
],
additionalAppClients: [
{
name: 'mcp-client',
generateSecret: true,
oauth: {
flows: ['code'],
scopes: ['openid', 'mcp/access'],
callbackUrls: ['https://claude.ai/api/mcp/auth_callback'],
},
},
],
});
```
Each additional client gets its own `AppClientId` output (e.g. `AppClientIdMcpClient`).
## Template Outputs
The template provides these CloudFormation outputs for integration:
| Output | Description | Condition |
| -------------------------- | ---------------------------------------------------------- | ----------------------------------- |
| `Region` | AWS region for Amplify Auth `region` | Always |
| `UserPoolId` | Cognito User Pool ID | Always |
| `AppClientId` | Default public client ID for Amplify `userPoolWebClientId` | Always |
| `IdentityPoolId` | Identity Pool ID | When `identityPool.enabled` |
| `CognitoUserPoolDomainUrl` | Hosted UI domain URL | When `domain` is set |
| `AppClientId` | Additional app client IDs | Per entry in `additionalAppClients` |
Access outputs in other CloudFormation templates:
```yaml
AuthConfig:
UserPoolId: !ImportValue MyAuthStack:UserPoolId
AppClientId: !ImportValue MyAuthStack:AppClientId
McpClientId: !ImportValue MyAuthStack:AppClientIdMcpClient
```
## Advanced Configuration
### Custom User Attributes
Define application-specific user attributes with validation:
```typescript
const template = createAuthTemplate({
schema: [
{
attributeDataType: 'Number',
name: 'employee_id',
required: true,
mutable: false,
numberAttributeConstraints: {
minValue: '1000',
maxValue: '99999',
},
},
{
attributeDataType: 'String',
name: 'department',
required: false,
mutable: true,
stringAttributeConstraints: {
minLength: '2',
maxLength: '50',
},
},
],
});
```
### End-to-End OAuth for Remote MCP Connectors
This example wires `@ttoss/cloud-auth` with `@ttoss/http-server-mcp` so Claude (or any OAuth 2.1 client) can authenticate against your MCP server using authorization code + PKCE:
```typescript
// cloudformation.ts
export default createAuthTemplate({
domain: { domainName: 'my-app' },
resourceServers: [
{
identifier: 'mcp',
name: 'MCP Server',
scopes: [{ scopeName: 'access', scopeDescription: 'Full MCP access' }],
},
],
additionalAppClients: [
{
name: 'mcp-client',
generateSecret: true,
oauth: {
flows: ['code'],
scopes: ['openid', 'mcp/access'],
callbackUrls: ['https://claude.ai/api/mcp/auth_callback'],
},
},
],
});
```
```typescript
// server.ts
const mcpRouter = createMcpRouter({
auth: {
cognitoUserPool: {
userPoolId: process.env.USER_POOL_ID,
clientId: process.env.MCP_CLIENT_ID, // AppClientIdMcpClient output
requiredScopes: ['mcp/access'],
},
},
// ...tools
});
```
The MCP client flow:
1. Client calls your MCP server → `401`.
2. Client reads `/.well-known/oauth-protected-resource` → discovers the Cognito authorization server URL (`CognitoUserPoolDomainUrl` output).
3. Client runs authorization code + PKCE through the Cognito hosted UI.
4. `createMcpRouter` verifies the access token and enforces `mcp/access`.
### Production Considerations
For production deployments:
- Use `Fn::GetAtt` references instead of hardcoded ARNs for Lambda functions
- Enable deletion protection (`deletionProtection: 'ACTIVE'`) for production user pools
- Configure appropriate IAM roles with minimal required permissions for Lambda functions
- Implement proper error handling in Lambda triggers to prevent authentication failures
- Set up monitoring and alerting for authentication metrics
- Consider regional failover strategies
## Related Resources
- [AWS Cognito User Pools Documentation](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html)
- [Lambda Triggers Reference](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-working-with-lambda-triggers.html)
- [Attribute-Based Access Control](https://docs.aws.amazon.com/cognito/latest/developerguide/attributes-for-access-control.html)
---
## Type Alias: AdditionalAppClientConfig
> **AdditionalAppClientConfig** = `object`
Defined in: [cloud-auth/src/template-hosted-ui.ts:30](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L30)
## Properties
### generateSecret?
> `optional` **generateSecret?**: `boolean`
Defined in: [cloud-auth/src/template-hosted-ui.ts:32](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L32)
***
### name
> **name**: `string`
Defined in: [cloud-auth/src/template-hosted-ui.ts:31](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L31)
***
### oauth?
> `optional` **oauth?**: [`OAuthConfig`](OAuthConfig.md)
Defined in: [cloud-auth/src/template-hosted-ui.ts:33](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L33)
---
## Type Alias: CloudFormationTemplate
> **CloudFormationTemplate** = `object`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:150](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L150)
## Properties
### AWSTemplateFormatVersion
> **AWSTemplateFormatVersion**: `"2010-09-09"`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:151](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L151)
***
### Conditions?
> `optional` **Conditions?**: `Conditions`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:156](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L156)
***
### Description?
> `optional` **Description?**: `string`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:153](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L153)
***
### Mappings?
> `optional` **Mappings?**: `Record`\<`string`, `Record`\<`string`, `Record`\<`string`, `string` \| `number`\>\>\>
Defined in: [cloudformation/src/CloudFormationTemplate.ts:155](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L155)
***
### Metadata?
> `optional` **Metadata?**: `Record`\<`string`, `any`\>
Defined in: [cloudformation/src/CloudFormationTemplate.ts:152](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L152)
***
### Outputs?
> `optional` **Outputs?**: `Outputs`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:159](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L159)
***
### Parameters?
> `optional` **Parameters?**: `Parameters`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:157](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L157)
***
### Resources
> **Resources**: `Resources`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:158](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L158)
***
### Transform?
> `optional` **Transform?**: `"AWS::Serverless-2016-10-31"` \| `string`[]
Defined in: [cloudformation/src/CloudFormationTemplate.ts:154](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L154)
---
## Type Alias: DomainConfig
> **DomainConfig** = `object`
Defined in: [cloud-auth/src/template-hosted-ui.ts:7](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L7)
## Properties
### certificateArn?
> `optional` **certificateArn?**: `string`
Defined in: [cloud-auth/src/template-hosted-ui.ts:9](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L9)
***
### domainName
> **domainName**: `string`
Defined in: [cloud-auth/src/template-hosted-ui.ts:8](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L8)
---
## Type Alias: IdentityPoolConfig
> **IdentityPoolConfig** = `object`
Defined in: [cloud-auth/src/template-identity-pool.ts:19](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-identity-pool.ts#L19)
## Properties
### allowUnauthenticatedIdentities?
> `optional` **allowUnauthenticatedIdentities?**: `boolean`
Defined in: [cloud-auth/src/template-identity-pool.ts:22](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-identity-pool.ts#L22)
***
### authenticatedPolicies?
> `optional` **authenticatedPolicies?**: `Policy`[]
Defined in: [cloud-auth/src/template-identity-pool.ts:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-identity-pool.ts#L24)
***
### authenticatedRoleArn?
> `optional` **authenticatedRoleArn?**: `string`
Defined in: [cloud-auth/src/template-identity-pool.ts:23](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-identity-pool.ts#L23)
***
### enabled?
> `optional` **enabled?**: `boolean`
Defined in: [cloud-auth/src/template-identity-pool.ts:20](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-identity-pool.ts#L20)
***
### name?
> `optional` **name?**: `string`
Defined in: [cloud-auth/src/template-identity-pool.ts:21](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-identity-pool.ts#L21)
***
### principalTags?
> `optional` **principalTags?**: `Record`\<`string`, `string`\> \| `boolean`
Defined in: [cloud-auth/src/template-identity-pool.ts:27](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-identity-pool.ts#L27)
***
### unauthenticatedPolicies?
> `optional` **unauthenticatedPolicies?**: `Policy`[]
Defined in: [cloud-auth/src/template-identity-pool.ts:26](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-identity-pool.ts#L26)
***
### unauthenticatedRoleArn?
> `optional` **unauthenticatedRoleArn?**: `string`
Defined in: [cloud-auth/src/template-identity-pool.ts:25](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-identity-pool.ts#L25)
---
## Type Alias: IdentityProviderConfig
> **IdentityProviderConfig** = `object`
Defined in: [cloud-auth/src/template-identity-providers.ts:10](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-identity-providers.ts#L10)
## Properties
### attributeMapping?
> `optional` **attributeMapping?**: `Record`\<`string`, `string`\>
Defined in: [cloud-auth/src/template-identity-providers.ts:23](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-identity-providers.ts#L23)
Maps provider attributes to user pool attributes. Defaults to
`{ email: 'email' }`.
***
### clientId
> **clientId**: `string`
Defined in: [cloud-auth/src/template-identity-providers.ts:12](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-identity-providers.ts#L12)
***
### clientSecret
> **clientSecret**: `string`
Defined in: [cloud-auth/src/template-identity-providers.ts:13](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-identity-providers.ts#L13)
***
### providerType
> **providerType**: [`IdentityProviderType`](IdentityProviderType.md)
Defined in: [cloud-auth/src/template-identity-providers.ts:11](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-identity-providers.ts#L11)
***
### scopes?
> `optional` **scopes?**: `string`[]
Defined in: [cloud-auth/src/template-identity-providers.ts:18](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-identity-providers.ts#L18)
Scopes requested from the provider. Defaults to the minimum needed to
populate the user pool's `email` attribute.
---
## Type Alias: IdentityProviderType
> **IdentityProviderType** = `"Google"` \| `"Facebook"`
Defined in: [cloud-auth/src/template-identity-providers.ts:8](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-identity-providers.ts#L8)
---
## Type Alias: OAuthConfig
> **OAuthConfig** = `object`
Defined in: [cloud-auth/src/template-hosted-ui.ts:23](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L23)
## Properties
### callbackUrls
> **callbackUrls**: `string`[]
Defined in: [cloud-auth/src/template-hosted-ui.ts:26](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L26)
***
### flows
> **flows**: (`"code"` \| `"implicit"` \| `"client_credentials"`)[]
Defined in: [cloud-auth/src/template-hosted-ui.ts:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L24)
***
### logoutUrls?
> `optional` **logoutUrls?**: `string`[]
Defined in: [cloud-auth/src/template-hosted-ui.ts:27](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L27)
***
### scopes
> **scopes**: `string`[]
Defined in: [cloud-auth/src/template-hosted-ui.ts:25](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L25)
---
## Type Alias: ResourceServerConfig
> **ResourceServerConfig** = `object`
Defined in: [cloud-auth/src/template-hosted-ui.ts:17](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L17)
## Properties
### identifier
> **identifier**: `string`
Defined in: [cloud-auth/src/template-hosted-ui.ts:18](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L18)
***
### name
> **name**: `string`
Defined in: [cloud-auth/src/template-hosted-ui.ts:19](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L19)
***
### scopes
> **scopes**: [`ResourceServerScope`](ResourceServerScope.md)[]
Defined in: [cloud-auth/src/template-hosted-ui.ts:20](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L20)
---
## Type Alias: ResourceServerScope
> **ResourceServerScope** = `object`
Defined in: [cloud-auth/src/template-hosted-ui.ts:12](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L12)
## Properties
### scopeDescription
> **scopeDescription**: `string`
Defined in: [cloud-auth/src/template-hosted-ui.ts:14](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L14)
***
### scopeName
> **scopeName**: `string`
Defined in: [cloud-auth/src/template-hosted-ui.ts:13](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-hosted-ui.ts#L13)
---
## Variable: DenyStatement
> `const` **DenyStatement**: `object`
Defined in: [cloud-auth/src/template.ts:50](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template.ts#L50)
## Type Declaration
### Action
> **Action**: `string`[]
### Effect
> **Effect**: `"Deny"`
### Resource
> **Resource**: `string`[]
---
## Variable: PASSWORD\_MINIMUM\_LENGTH
> `const` **PASSWORD\_MINIMUM\_LENGTH**: `8` = `8`
Defined in: [cloud-auth/src/config.ts:1](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/config.ts#L1)
---
## Variable: defaultPrincipalTags
> `const` **defaultPrincipalTags**: `object`
Defined in: [cloud-auth/src/template-identity-pool.ts:104](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-auth/src/template-identity-pool.ts#L104)
## Type Declaration
### appClientId
> **appClientId**: `string` = `'aud'`
### userId
> **userId**: `string` = `'sub'`
---
## Function: createRolesTemplate()
> **createRolesTemplate**(`__namedParameters`): `any`
Defined in: [cloud-roles/src/index.ts:11](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-roles/src/index.ts#L11)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | \{ `path?`: `string`; `resources`: \{\[`key`: `string`\]: [`IAMRoleResource`](../type-aliases/IAMRoleResource.md); \}; \} |
| `__namedParameters.path?` | `string` |
| `__namedParameters.resources` | \{\[`key`: `string`\]: [`IAMRoleResource`](../type-aliases/IAMRoleResource.md); \} |
## Returns
`any`
---
## @ttoss/cloud-roles
## Type Aliases
- [CloudFormationTemplate](type-aliases/CloudFormationTemplate.md)
- [IAMRoleResource](type-aliases/IAMRoleResource.md)
- [Outputs](type-aliases/Outputs.md)
## Variables
- [IAM\_PATH](variables/IAM_PATH.md)
## Functions
- [createRolesTemplate](functions/createRolesTemplate.md)
---
## @ttoss/cloud-roles(Cloud-roles)
Create CloudFormation templates for IAM roles with TypeScript.
## Installation
```bash
pnpm add @ttoss/cloud-roles
```
## Usage
```typescript
const template = createRolesTemplate({
resources: {
AppSyncLambdaFunctionIAMRole: {
Type: 'AWS::IAM::Role',
Properties: {
AssumeRolePolicyDocument: {
Version: '2012-10-17',
Statement: [
{
Effect: 'Allow',
Action: 'sts:AssumeRole',
Principal: { Service: 'lambda.amazonaws.com' },
},
],
},
ManagedPolicyArns: [
'arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole',
],
},
},
},
});
export default template;
```
## API
### `createRolesTemplate`
Generates a CloudFormation template containing one or more `AWS::IAM::Role` resources and automatically exports each role's ARN as a stack output.
#### Parameters
- `resources: { [key: string]: IAMRoleResource }` — map of logical resource IDs to `AWS::IAM::Role` resource definitions.
- `path?: string` — IAM path applied to every role that does not already define `Properties.Path`. Defaults to `IAM_PATH` (`'/custom-iam/'`). IAM (and thus CloudFormation) requires paths to begin and end with `/` (e.g. `'/my-app/'`); `createRolesTemplate` does not validate this, so an invalid path will cause a deploy-time error.
#### Behavior
- Any role in `resources` that has no `Properties.Path` set will have its `Path` automatically set to the resolved `path` value.
- For every role, a stack output named `Arn` is added, exporting the role ARN under the key `:Arn`.
- `createRolesTemplate` mutates the provided `resources` objects by setting `resource.Properties.Path` when it is missing. If you need to reuse the same resource definitions elsewhere, clone them before passing them to this function.
#### Overriding the default path
```typescript
const template = createRolesTemplate({
path: '/my-app/',
resources: {
/* ... */
},
});
```
Roles that already declare `Properties.Path` are left unchanged.
### `IAM_PATH`
The default IAM path constant used when `path` is not provided:
```typescript
console.log(IAM_PATH); // '/custom-iam/'
```
## Security: restricting `iam:PassRole` with IAM paths
Setting a dedicated IAM path for application roles enables a simple but effective deployment security boundary.
**Pattern:**
1. Create all application roles centrally with `createRolesTemplate` (keeping them under `/custom-iam/` or a custom path).
2. Grant deployment users `iam:PassRole` only for roles under that path.
3. Deny deployment users the ability to create, update, tag, or delete IAM roles.
This separates _privileged IAM management_ (run infrequently, with elevated permissions) from _regular application deployment_ (run on every release, with limited permissions).
**Example deployment policy:**
```yaml
- Effect: Allow
Action:
- iam:PassRole
Resource:
- arn:aws:iam::*:role/custom-iam/*
Condition:
StringEquals:
iam:PassedToService:
- lambda.amazonaws.com
- appsync.amazonaws.com
```
With this policy, a deployment pipeline can attach centrally managed roles to Lambda functions and AppSync data sources, but cannot create or modify those roles itself.
---
## Type Alias: CloudFormationTemplate(Type-aliases)
> **CloudFormationTemplate** = `object`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:150](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L150)
## Properties
### AWSTemplateFormatVersion
> **AWSTemplateFormatVersion**: `"2010-09-09"`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:151](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L151)
***
### Conditions?
> `optional` **Conditions?**: `Conditions`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:156](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L156)
***
### Description?
> `optional` **Description?**: `string`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:153](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L153)
***
### Mappings?
> `optional` **Mappings?**: `Record`\<`string`, `Record`\<`string`, `Record`\<`string`, `string` \| `number`\>\>\>
Defined in: [cloudformation/src/CloudFormationTemplate.ts:155](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L155)
***
### Metadata?
> `optional` **Metadata?**: `Record`\<`string`, `any`\>
Defined in: [cloudformation/src/CloudFormationTemplate.ts:152](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L152)
***
### Outputs?
> `optional` **Outputs?**: [`Outputs`](Outputs.md)
Defined in: [cloudformation/src/CloudFormationTemplate.ts:159](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L159)
***
### Parameters?
> `optional` **Parameters?**: `Parameters`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:157](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L157)
***
### Resources
> **Resources**: `Resources`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:158](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L158)
***
### Transform?
> `optional` **Transform?**: `"AWS::Serverless-2016-10-31"` \| `string`[]
Defined in: [cloudformation/src/CloudFormationTemplate.ts:154](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L154)
---
## Type Alias: IAMRoleResource
> **IAMRoleResource** = `BaseResource` & `object`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:122](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L122)
## Type Declaration
### Properties
> **Properties**: `object`
#### Properties.AssumeRolePolicyDocument
> **AssumeRolePolicyDocument**: `PolicyDocument`
#### Properties.Description?
> `optional` **Description?**: `string`
#### Properties.ManagedPolicyArns?
> `optional` **ManagedPolicyArns?**: `CloudFormationValue`\<`string`[]\>
#### Properties.MaxSessionDuration?
> `optional` **MaxSessionDuration?**: `number`
#### Properties.Path?
> `optional` **Path?**: `string`
#### Properties.PermissionsBoundary?
> `optional` **PermissionsBoundary?**: `CloudFormationValue`\<`string`\>
#### Properties.Policies?
> `optional` **Policies?**: `Policy`[]
#### Properties.RoleName?
> `optional` **RoleName?**: `CloudFormationValue`\<`string`\>
#### Properties.Tags?
> `optional` **Tags?**: `object`[]
### Type
> **Type**: `"AWS::IAM::Role"`
---
## Type Alias: Outputs
> **Outputs** = `Record`\<`string`, `Output`\>
Defined in: [cloudformation/src/CloudFormationTemplate.ts:148](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L148)
---
## Variable: IAM\_PATH
> `const` **IAM\_PATH**: `"/custom-iam/"` = `'/custom-iam/'`
Defined in: [cloud-roles/src/index.ts:7](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-roles/src/index.ts#L7)
---
## Function: createVpcTemplate()
> **createVpcTemplate**(`__namedParameters`): [`CloudFormationTemplate`](../type-aliases/CloudFormationTemplate.md)
Defined in: [cloud-vpc/src/index.ts:11](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloud-vpc/src/index.ts#L11)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | \{ `cidrBlock`: `string`; `createPublicSubnets?`: `boolean`; \} |
| `__namedParameters.cidrBlock` | `string` |
| `__namedParameters.createPublicSubnets?` | `boolean` |
## Returns
[`CloudFormationTemplate`](../type-aliases/CloudFormationTemplate.md)
---
## @ttoss/cloud-vpc
## Type Aliases
- [CloudFormationTemplate](type-aliases/CloudFormationTemplate.md)
## Functions
- [createVpcTemplate](functions/createVpcTemplate.md)
---
## @ttoss/cloud-vpc(Cloud-vpc)
This module provides a set of resources to create a VPC on AWS.
## Installation
```bash
pnpm install @ttoss/cloud-vpc
```
## Usage
```typescript
const cidrBlock = '10.0.0.0/16';
const template = createVpcTemplate({
cidrBlock,
});
export default template;
```
## API
### `createVpcTemplate`
Creates a VPC template.
#### Parameters
- `cidrBlock: string` - The CIDR block of the VPC.
- `createPublicSubnets: boolean` - Whether to create public subnets. Default is `true`.
---
## Type Alias: CloudFormationTemplate(3)
> **CloudFormationTemplate** = `object`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:150](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L150)
## Properties
### AWSTemplateFormatVersion
> **AWSTemplateFormatVersion**: `"2010-09-09"`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:151](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L151)
***
### Conditions?
> `optional` **Conditions?**: `Conditions`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:156](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L156)
***
### Description?
> `optional` **Description?**: `string`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:153](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L153)
***
### Mappings?
> `optional` **Mappings?**: `Record`\<`string`, `Record`\<`string`, `Record`\<`string`, `string` \| `number`\>\>\>
Defined in: [cloudformation/src/CloudFormationTemplate.ts:155](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L155)
***
### Metadata?
> `optional` **Metadata?**: `Record`\<`string`, `any`\>
Defined in: [cloudformation/src/CloudFormationTemplate.ts:152](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L152)
***
### Outputs?
> `optional` **Outputs?**: `Outputs`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:159](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L159)
***
### Parameters?
> `optional` **Parameters?**: `Parameters`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:157](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L157)
***
### Resources
> **Resources**: `Resources`
Defined in: [cloudformation/src/CloudFormationTemplate.ts:158](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L158)
***
### Transform?
> `optional` **Transform?**: `"AWS::Serverless-2016-10-31"` \| `string`[]
Defined in: [cloudformation/src/CloudFormationTemplate.ts:154](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L154)
---
## Function: findAndReadCloudFormationTemplate()
> **findAndReadCloudFormationTemplate**(`__namedParameters`): `Promise`\<[`CloudFormationTemplate`](../type-aliases/CloudFormationTemplate.md)\>
Defined in: [findAndReadCloudFormationTemplate.ts:15](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/findAndReadCloudFormationTemplate.ts#L15)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | \{ `options?`: `unknown`; `templatePath?`: `string`; \} |
| `__namedParameters.options?` | `unknown` |
| `__namedParameters.templatePath?` | `string` |
## Returns
`Promise`\<[`CloudFormationTemplate`](../type-aliases/CloudFormationTemplate.md)\>
---
## Function: importValueFromParameter()
> **importValueFromParameter**(`parameterName`): [`CloudFormationImportValue`](../type-aliases/CloudFormationImportValue.md)
Defined in: [CloudFormationTemplate.ts:25](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L25)
Returns an `Fn::ImportValue` intrinsic that resolves the export name from
a CloudFormation parameter via `Fn::Sub`.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `parameterName` | `string` |
## Returns
[`CloudFormationImportValue`](../type-aliases/CloudFormationImportValue.md)
## Example
```ts
importValueFromParameter('MyStackExportName')
// => { 'Fn::ImportValue': { 'Fn::Sub': '${MyStackExportName}' } }
```
---
## @ttoss/cloudformation
## Type Aliases
- [BaseResource](type-aliases/BaseResource.md)
- [CloudFormationGetAtt](type-aliases/CloudFormationGetAtt.md)
- [CloudFormationImportValue](type-aliases/CloudFormationImportValue.md)
- [CloudFormationIntrinsic](type-aliases/CloudFormationIntrinsic.md)
- [CloudFormationJoin](type-aliases/CloudFormationJoin.md)
- [CloudFormationRef](type-aliases/CloudFormationRef.md)
- [CloudFormationSelect](type-aliases/CloudFormationSelect.md)
- [CloudFormationSplit](type-aliases/CloudFormationSplit.md)
- [CloudFormationSub](type-aliases/CloudFormationSub.md)
- [CloudFormationTemplate](type-aliases/CloudFormationTemplate.md)
- [CloudFormationValue](type-aliases/CloudFormationValue.md)
- [Condition](type-aliases/Condition.md)
- [Conditions](type-aliases/Conditions.md)
- [IAMRoleResource](type-aliases/IAMRoleResource.md)
- [Output](type-aliases/Output.md)
- [Outputs](type-aliases/Outputs.md)
- [Parameter](type-aliases/Parameter.md)
- [Parameters](type-aliases/Parameters.md)
- [Policy](type-aliases/Policy.md)
- [PolicyDocument](type-aliases/PolicyDocument.md)
- [PolicyStatement](type-aliases/PolicyStatement.md)
- [Resource](type-aliases/Resource.md)
- [Resources](type-aliases/Resources.md)
## Functions
- [findAndReadCloudFormationTemplate](functions/findAndReadCloudFormationTemplate.md)
- [importValueFromParameter](functions/importValueFromParameter.md)
---
## @ttoss/cloudformation(Cloudformation)
Utilities and TypeScript types for working with AWS CloudFormation templates.
## Installation
```bash
pnpm add @ttoss/cloudformation
```
## Intrinsic Function Types
The package exports TypeScript types for all commonly used CloudFormation intrinsic functions:
| Type | CloudFormation equivalent |
| --------------------------- | ---------------------------------------------------- |
| `CloudFormationRef` | `{ Ref: string }` |
| `CloudFormationGetAtt` | `{ 'Fn::GetAtt': [string, string] }` |
| `CloudFormationJoin` | `{ 'Fn::Join': [string, ...] }` |
| `CloudFormationSub` | `{ 'Fn::Sub': string }` |
| `CloudFormationSelect` | `{ 'Fn::Select': [number, string[]] }` |
| `CloudFormationSplit` | `{ 'Fn::Split': [string, string] }` |
| `CloudFormationImportValue` | `{ 'Fn::ImportValue': string \| CloudFormationSub }` |
| `CloudFormationIntrinsic` | Union of all the above |
| `CloudFormationValue` | `T \| CloudFormationIntrinsic` |
## Helpers
### `importValueFromParameter`
Generates an `Fn::ImportValue` + `Fn::Sub` intrinsic that reads the export name
from a CloudFormation parameter. This is the standard pattern for consuming
cross-stack exports whose names are not known at author time.
```typescript
importValueFromParameter('AppSyncLambdaRoleArn');
// => { 'Fn::ImportValue': { 'Fn::Sub': '${AppSyncLambdaRoleArn}' } }
```
Typical use in a CloudFormation template:
```typescript
const template = createApiTemplate({
schemaComposer,
dataSource: {
roleArn: importValueFromParameter('AppSyncLambdaDataSourceIAMRoleArn'),
},
lambdaFunction: {
roleArn: importValueFromParameter('AppSyncLambdaFunctionIAMRoleArn'),
environment: {
variables: {
TABLE_NAME: { Ref: 'DynamoTableName' },
EXTERNAL_ARN: importValueFromParameter('SomeOtherStackExportedName'),
},
},
},
});
```
When a producing stack exports a value and a consuming stack imports it with
`Fn::ImportValue`, CloudFormation protects that dependency by blocking deletion
of the producer export until imports are removed.
Producer stack output example:
```typescript
const outputs = {
LambdaPostgresReadQueryFunctionArn: {
Value: { 'Fn::GetAtt': ['LambdaPostgresReadQueryFunction', 'Arn'] },
Export: {
Name: {
'Fn::Sub': '${AWS::StackName}-LambdaPostgresReadQueryFunctionArn',
},
},
},
};
```
Consumer stack usage with parameterized export name:
```typescript
const resources = {
InvokePermission: {
Type: 'AWS::Lambda::Permission',
Properties: {
FunctionName: importValueFromParameter('ReadQueryFunctionArnExportName'),
Action: 'lambda:InvokeFunction',
Principal: 'apigateway.amazonaws.com',
},
},
};
```
## Reading Templates
### `findAndReadCloudFormationTemplate`
Reads a CloudFormation template file from disk. Supports both TypeScript and
YAML files.
```typescript
const template = await findAndReadCloudFormationTemplate({
templatePath: './cloudformation.ts',
options: { environment: 'Production' },
});
```
---
## Type Alias: BaseResource
> **BaseResource** = `object`
Defined in: [CloudFormationTemplate.ts:106](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L106)
## Properties
### Condition?
> `optional` **Condition?**: `string`
Defined in: [CloudFormationTemplate.ts:112](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L112)
***
### CreationPolicy?
> `optional` **CreationPolicy?**: `Record`\<`string`, `any`\>
Defined in: [CloudFormationTemplate.ts:114](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L114)
***
### DeletionPolicy?
> `optional` **DeletionPolicy?**: `"Delete"` \| `"Retain"` \| `"Snapshot"`
Defined in: [CloudFormationTemplate.ts:108](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L108)
***
### DependsOn?
> `optional` **DependsOn?**: `string` \| `string`[]
Defined in: [CloudFormationTemplate.ts:111](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L111)
***
### Description?
> `optional` **Description?**: `string`
Defined in: [CloudFormationTemplate.ts:110](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L110)
***
### Metadata?
> `optional` **Metadata?**: `Record`\<`string`, `any`\>
Defined in: [CloudFormationTemplate.ts:113](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L113)
***
### Type
> **Type**: `string`
Defined in: [CloudFormationTemplate.ts:107](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L107)
***
### UpdatePolicy?
> `optional` **UpdatePolicy?**: `Record`\<`string`, `any`\>
Defined in: [CloudFormationTemplate.ts:115](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L115)
***
### UpdateReplacePolicy?
> `optional` **UpdateReplacePolicy?**: `"Delete"` \| `"Retain"` \| `"Snapshot"`
Defined in: [CloudFormationTemplate.ts:109](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L109)
---
## Type Alias: CloudFormationGetAtt
> **CloudFormationGetAtt** = `object`
Defined in: [CloudFormationTemplate.ts:4](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L4)
## Properties
### Fn::GetAtt
> **Fn::GetAtt**: \[`string`, `string`\]
Defined in: [CloudFormationTemplate.ts:4](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L4)
---
## Type Alias: CloudFormationImportValue
> **CloudFormationImportValue** = `object`
Defined in: [CloudFormationTemplate.ts:13](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L13)
## Properties
### Fn::ImportValue
> **Fn::ImportValue**: `string` \| [`CloudFormationSub`](CloudFormationSub.md)
Defined in: [CloudFormationTemplate.ts:14](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L14)
---
## Type Alias: CloudFormationIntrinsic
> **CloudFormationIntrinsic** = [`CloudFormationRef`](CloudFormationRef.md) \| [`CloudFormationGetAtt`](CloudFormationGetAtt.md) \| [`CloudFormationJoin`](CloudFormationJoin.md) \| [`CloudFormationSub`](CloudFormationSub.md) \| [`CloudFormationSelect`](CloudFormationSelect.md) \| [`CloudFormationSplit`](CloudFormationSplit.md) \| [`CloudFormationImportValue`](CloudFormationImportValue.md)
Defined in: [CloudFormationTemplate.ts:35](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L35)
---
## Type Alias: CloudFormationJoin
> **CloudFormationJoin** = `object`
Defined in: [CloudFormationTemplate.ts:5](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L5)
## Properties
### Fn::Join
> **Fn::Join**: \[`string`, (`string` \| [`CloudFormationRef`](CloudFormationRef.md))[]\]
Defined in: [CloudFormationTemplate.ts:6](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L6)
---
## Type Alias: CloudFormationRef
> **CloudFormationRef** = `object`
Defined in: [CloudFormationTemplate.ts:3](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L3)
## Properties
### Ref
> **Ref**: `string`
Defined in: [CloudFormationTemplate.ts:3](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L3)
---
## Type Alias: CloudFormationSelect
> **CloudFormationSelect** = `object`
Defined in: [CloudFormationTemplate.ts:11](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L11)
## Properties
### Fn::Select
> **Fn::Select**: \[`number`, `string`[]\]
Defined in: [CloudFormationTemplate.ts:11](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L11)
---
## Type Alias: CloudFormationSplit
> **CloudFormationSplit** = `object`
Defined in: [CloudFormationTemplate.ts:12](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L12)
## Properties
### Fn::Split
> **Fn::Split**: \[`string`, `string`\]
Defined in: [CloudFormationTemplate.ts:12](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L12)
---
## Type Alias: CloudFormationSub
> **CloudFormationSub** = `object`
Defined in: [CloudFormationTemplate.ts:8](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L8)
## Properties
### Fn::Sub
> **Fn::Sub**: `string` \| \[`string`, `Record`\<`string`, `any`\>\]
Defined in: [CloudFormationTemplate.ts:9](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L9)
---
## Type Alias: CloudFormationTemplate(4)
> **CloudFormationTemplate** = `object`
Defined in: [CloudFormationTemplate.ts:150](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L150)
## Properties
### AWSTemplateFormatVersion
> **AWSTemplateFormatVersion**: `"2010-09-09"`
Defined in: [CloudFormationTemplate.ts:151](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L151)
***
### Conditions?
> `optional` **Conditions?**: [`Conditions`](Conditions.md)
Defined in: [CloudFormationTemplate.ts:156](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L156)
***
### Description?
> `optional` **Description?**: `string`
Defined in: [CloudFormationTemplate.ts:153](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L153)
***
### Mappings?
> `optional` **Mappings?**: `Record`\<`string`, `Record`\<`string`, `Record`\<`string`, `string` \| `number`\>\>\>
Defined in: [CloudFormationTemplate.ts:155](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L155)
***
### Metadata?
> `optional` **Metadata?**: `Record`\<`string`, `any`\>
Defined in: [CloudFormationTemplate.ts:152](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L152)
***
### Outputs?
> `optional` **Outputs?**: [`Outputs`](Outputs.md)
Defined in: [CloudFormationTemplate.ts:159](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L159)
***
### Parameters?
> `optional` **Parameters?**: [`Parameters`](Parameters.md)
Defined in: [CloudFormationTemplate.ts:157](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L157)
***
### Resources
> **Resources**: [`Resources`](Resources.md)
Defined in: [CloudFormationTemplate.ts:158](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L158)
***
### Transform?
> `optional` **Transform?**: `"AWS::Serverless-2016-10-31"` \| `string`[]
Defined in: [CloudFormationTemplate.ts:154](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L154)
---
## Type Alias: CloudFormationValue\
> **CloudFormationValue**\<`T`\> = `T` \| [`CloudFormationIntrinsic`](CloudFormationIntrinsic.md)
Defined in: [CloudFormationTemplate.ts:44](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L44)
## Type Parameters
| Type Parameter | Default type |
| ------ | ------ |
| `T` | `any` |
---
## Type Alias: Condition
> **Condition** = `Record`\<`string`, `any`\>
Defined in: [CloudFormationTemplate.ts:73](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L73)
---
## Type Alias: Conditions
> **Conditions** = `Record`\<`string`, [`Condition`](Condition.md)\>
Defined in: [CloudFormationTemplate.ts:74](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L74)
---
## Type Alias: IAMRoleResource(Type-aliases)
> **IAMRoleResource** = [`BaseResource`](BaseResource.md) & `object`
Defined in: [CloudFormationTemplate.ts:122](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L122)
## Type Declaration
### Properties
> **Properties**: `object`
#### Properties.AssumeRolePolicyDocument
> **AssumeRolePolicyDocument**: [`PolicyDocument`](PolicyDocument.md)
#### Properties.Description?
> `optional` **Description?**: `string`
#### Properties.ManagedPolicyArns?
> `optional` **ManagedPolicyArns?**: [`CloudFormationValue`](CloudFormationValue.md)\<`string`[]\>
#### Properties.MaxSessionDuration?
> `optional` **MaxSessionDuration?**: `number`
#### Properties.Path?
> `optional` **Path?**: `string`
#### Properties.PermissionsBoundary?
> `optional` **PermissionsBoundary?**: [`CloudFormationValue`](CloudFormationValue.md)\<`string`\>
#### Properties.Policies?
> `optional` **Policies?**: [`Policy`](Policy.md)[]
#### Properties.RoleName?
> `optional` **RoleName?**: [`CloudFormationValue`](CloudFormationValue.md)\<`string`\>
#### Properties.Tags?
> `optional` **Tags?**: `object`[]
### Type
> **Type**: `"AWS::IAM::Role"`
---
## Type Alias: Output
> **Output** = `object`
Defined in: [CloudFormationTemplate.ts:139](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L139)
## Properties
### Condition?
> `optional` **Condition?**: `string`
Defined in: [CloudFormationTemplate.ts:145](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L145)
***
### Description?
> `optional` **Description?**: `string`
Defined in: [CloudFormationTemplate.ts:140](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L140)
***
### Export?
> `optional` **Export?**: `object`
Defined in: [CloudFormationTemplate.ts:142](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L142)
#### Name
> **Name**: [`CloudFormationValue`](CloudFormationValue.md)\<`string`\>
***
### Value
> **Value**: [`CloudFormationValue`](CloudFormationValue.md)
Defined in: [CloudFormationTemplate.ts:141](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L141)
---
## Type Alias: Outputs(Type-aliases)
> **Outputs** = `Record`\<`string`, [`Output`](Output.md)\>
Defined in: [CloudFormationTemplate.ts:148](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L148)
---
## Type Alias: Parameter
> **Parameter** = `object`
Defined in: [CloudFormationTemplate.ts:46](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L46)
## Properties
### AllowedPattern?
> `optional` **AllowedPattern?**: `string`
Defined in: [CloudFormationTemplate.ts:67](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L67)
***
### AllowedValues?
> `optional` **AllowedValues?**: `string`[]
Defined in: [CloudFormationTemplate.ts:47](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L47)
***
### ConstraintDescription?
> `optional` **ConstraintDescription?**: `string`
Defined in: [CloudFormationTemplate.ts:68](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L68)
***
### Default?
> `optional` **Default?**: `string` \| `number` \| `boolean`
Defined in: [CloudFormationTemplate.ts:48](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L48)
***
### Description?
> `optional` **Description?**: `string`
Defined in: [CloudFormationTemplate.ts:49](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L49)
***
### MaxLength?
> `optional` **MaxLength?**: `number`
Defined in: [CloudFormationTemplate.ts:64](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L64)
***
### MaxValue?
> `optional` **MaxValue?**: `number`
Defined in: [CloudFormationTemplate.ts:66](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L66)
***
### MinLength?
> `optional` **MinLength?**: `number`
Defined in: [CloudFormationTemplate.ts:63](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L63)
***
### MinValue?
> `optional` **MinValue?**: `number`
Defined in: [CloudFormationTemplate.ts:65](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L65)
***
### NoEcho?
> `optional` **NoEcho?**: `boolean`
Defined in: [CloudFormationTemplate.ts:62](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L62)
***
### Type
> **Type**: `"String"` \| `"Number"` \| `"List"` \| `"CommaDelimitedList"` \| `"AWS::EC2::KeyPair::KeyName"` \| `"AWS::EC2::SecurityGroup::Id"` \| `"AWS::EC2::Subnet::Id"` \| `"AWS::EC2::VPC::Id"` \| `"List"` \| `"List"` \| `"List"`
Defined in: [CloudFormationTemplate.ts:50](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L50)
---
## Type Alias: Parameters
> **Parameters** = `Record`\<`string`, [`Parameter`](Parameter.md)\>
Defined in: [CloudFormationTemplate.ts:71](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L71)
---
## Type Alias: Policy
> **Policy** = `object`
Defined in: [CloudFormationTemplate.ts:101](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L101)
## Properties
### PolicyDocument
> **PolicyDocument**: [`PolicyDocument`](PolicyDocument.md)
Defined in: [CloudFormationTemplate.ts:103](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L103)
***
### PolicyName
> **PolicyName**: `string`
Defined in: [CloudFormationTemplate.ts:102](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L102)
---
## Type Alias: PolicyDocument
> **PolicyDocument** = `object`
Defined in: [CloudFormationTemplate.ts:95](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L95)
## Properties
### Id?
> `optional` **Id?**: `string`
Defined in: [CloudFormationTemplate.ts:97](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L97)
***
### Statement
> **Statement**: [`PolicyStatement`](PolicyStatement.md)[]
Defined in: [CloudFormationTemplate.ts:98](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L98)
***
### Version
> **Version**: `"2012-10-17"`
Defined in: [CloudFormationTemplate.ts:96](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L96)
---
## Type Alias: PolicyStatement
> **PolicyStatement** = `object`
Defined in: [CloudFormationTemplate.ts:76](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L76)
## Properties
### Action
> **Action**: `string` \| `string`[]
Defined in: [CloudFormationTemplate.ts:79](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L79)
***
### Condition?
> `optional` **Condition?**: `Record`\<`string`, `Record`\<`string`, [`CloudFormationValue`](CloudFormationValue.md)\<`string` \| `string`[]\>\>\>
Defined in: [CloudFormationTemplate.ts:82](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L82)
***
### Effect
> **Effect**: `"Allow"` \| `"Deny"`
Defined in: [CloudFormationTemplate.ts:78](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L78)
***
### NotAction?
> `optional` **NotAction?**: `string` \| `string`[]
Defined in: [CloudFormationTemplate.ts:86](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L86)
***
### NotPrincipal?
> `optional` **NotPrincipal?**: [`CloudFormationValue`](CloudFormationValue.md)\<`string` \| `Record`\<`string`, `string` \| `string`[]\>\>
Defined in: [CloudFormationTemplate.ts:90](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L90)
***
### NotResource?
> `optional` **NotResource?**: [`CloudFormationValue`](CloudFormationValue.md)\<`string`\> \| [`CloudFormationValue`](CloudFormationValue.md)\<`string`\>[]
Defined in: [CloudFormationTemplate.ts:87](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L87)
***
### Principal?
> `optional` **Principal?**: [`CloudFormationValue`](CloudFormationValue.md)\<`string` \| `Record`\<`string`, `string` \| `string`[]\>\>
Defined in: [CloudFormationTemplate.ts:81](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L81)
***
### Resource?
> `optional` **Resource?**: [`CloudFormationValue`](CloudFormationValue.md)\<`string`\> \| [`CloudFormationValue`](CloudFormationValue.md)\<`string`\>[]
Defined in: [CloudFormationTemplate.ts:80](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L80)
***
### Sid?
> `optional` **Sid?**: `string`
Defined in: [CloudFormationTemplate.ts:77](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L77)
---
## Type Alias: Resource
> **Resource** = [`BaseResource`](BaseResource.md) & `object`
Defined in: [CloudFormationTemplate.ts:118](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L118)
## Type Declaration
### Properties?
> `optional` **Properties?**: `Record`\<`string`, `any`\>
---
## Type Alias: Resources
> **Resources** = `Record`\<`string`, [`Resource`](Resource.md)\>
Defined in: [CloudFormationTemplate.ts:137](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/cloudformation/src/CloudFormationTemplate.ts#L137)
---
## Function: Accordion()
> **Accordion**(`__namedParameters`): `Element`
Defined in: [Accordion/Accordion.tsx:149](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Accordion/Accordion.tsx#L149)
Accessible accordion component with collapsible content sections.
This component provides a simplified API for creating expandable/collapsible
content sections. It uses design tokens from @ttoss/theme for consistent styling
and follows WAI-ARIA accordion pattern for accessibility.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | [`AccordionProps`](../type-aliases/AccordionProps.md) |
## Returns
`Element`
## Examples
```tsx
console.log('Expanded items:', expanded)}
/>
```
```tsx
// Custom rendering with renderItem
(
setIsOpen(false)}
header={{
icon: "fluent:lock-closed-24-filled",
title: "Premium Feature",
description: "Available in Pro plan only",
variant: "primary"
}}
actions={[
{
label: "Upgrade Now",
icon: "fluent-emoji-high-contrast:sparkles",
variant: "primary",
onClick: handleUpgrade
},
{
label: "Learn More",
icon: "fluent:arrow-right-16-regular",
variant: "accent",
onClick: handleLearnMore
}
]}
>
This feature is only available for Pro users.
```
```tsx
// Blocking a specific section with custom zIndex
Content here
```
---
## Function: Markdown()
> **Markdown**(`__namedParameters`): `Element`
Defined in: [Markdown/Markdown.tsx:13](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Markdown/Markdown.tsx#L13)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | [`MarkdownProps`](../type-aliases/MarkdownProps.md) |
## Returns
`Element`
---
## Function: Menu()
> **Menu**(`__namedParameters`): `Element`
Defined in: [Menu/Menu.tsx:11](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Menu/Menu.tsx#L11)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | [`MenuProps`](../type-aliases/MenuProps.md) |
## Returns
`Element`
---
## Function: MetricCard()
> **MetricCard**(`__namedParameters`): `Element` \| `null`
Defined in: [MetricCard/MetricCard.tsx:401](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.tsx#L401)
MetricCard component displays a metric in a consistent card layout.
It supports three metric types:
- **date**: displays a date and optional remaining-days message
- **percentage**: displays current/max values and a progress bar
- **number**: displays current/max values and an optional footer text
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | [`MetricCardProps`](../interfaces/MetricCardProps.md) |
## Returns
`Element` \| `null`
## Examples
```tsx
{
const res = await authorize({ variables: { scopes } });
return { ok: !!res.ok };
}}
onAuthorized={() => { window.location.href = resumeUrl; }}
onDeny={() => navigate('/')}
labels={labels}
/>
```
---
## Function: Search()
> **Search**(`__namedParameters`): `Element`
Defined in: [Search/Search.tsx:11](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Search/Search.tsx#L11)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | [`SearchProps`](../type-aliases/SearchProps.md) |
## Returns
`Element`
---
## Function: SpotlightCard()
> **SpotlightCard**(`__namedParameters`): `Element`
Defined in: [SpotlightCard/SpotlightCard.tsx:44](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/SpotlightCard/SpotlightCard.tsx#L44)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | [`SpotlightCardProps`](../type-aliases/SpotlightCardProps.md) |
## Returns
`Element`
---
## Function: Table()
> **Table**(`props`): `Element`
Defined in: [Table/Table.tsx:12](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Table/Table.tsx#L12)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `props` | `BoxProps` |
## Returns
`Element`
---
## Function: Tabs()
> **Tabs**(`props`): `Element`
Defined in: [Tabs/Tabs.tsx:16](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Tabs/Tabs.tsx#L16)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `props` | `BoxProps` & `TabsProps` |
## Returns
`Element`
---
## Function: ToastContainer()
> **ToastContainer**(`props`): `Element`
Defined in: [Toast/Toast.tsx:15](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Toast/Toast.tsx#L15)
## Parameters
| Parameter | Type |
| ------ | ------ |
| `props` | `ToastContainerProps` |
## Returns
`Element`
---
## Function: collectGrantedScopes()
> **collectGrantedScopes**(`scopes`, `selected`): `string`[]
Defined in: [OAuthConsent/OAuthConsent.tsx:116](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/OAuthConsent/OAuthConsent.tsx#L116)
Walk the scope tree and return the minimal set of granted scope keys.
When a node is selected, its key is emitted and its subtree is skipped
(the server expands parent scopes to their children). Nodes not in
`selected` are recursed into so that individually-selected children
are still captured.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `scopes` | [`ConsentScope`](../type-aliases/ConsentScope.md)[] |
| `selected` | `Set`\<`string`\> |
## Returns
`string`[]
---
## @ttoss/components
## Interfaces
- [BaseMetric](interfaces/BaseMetric.md)
- [DateMetric](interfaces/DateMetric.md)
- [DateRange](interfaces/DateRange.md)
- [EnhancedTitleBadge](interfaces/EnhancedTitleBadge.md)
- [EnhancedTitleProps](interfaces/EnhancedTitleProps.md)
- [ListItemProps](interfaces/ListItemProps.md)
- [ListProps](interfaces/ListProps.md)
- [MetricCardProps](interfaces/MetricCardProps.md)
- [NumberMetric](interfaces/NumberMetric.md)
- [PercentageMetric](interfaces/PercentageMetric.md)
## Type Aliases
- [AccordionItem](type-aliases/AccordionItem.md)
- [AccordionProps](type-aliases/AccordionProps.md)
- [AccordionRenderItemProps](type-aliases/AccordionRenderItemProps.md)
- [ConsentScope](type-aliases/ConsentScope.md)
- [DrawerProps](type-aliases/DrawerProps.md)
- [EnhancedTitleVariant](type-aliases/EnhancedTitleVariant.md)
- [FileUploaderProps](type-aliases/FileUploaderProps.md)
- [FileUploadState](type-aliases/FileUploadState.md)
- [InstallPwaUiProps](type-aliases/InstallPwaUiProps.md)
- [LinkComponentProps](type-aliases/LinkComponentProps.md)
- [MarkdownProps](type-aliases/MarkdownProps.md)
- [MenuProps](type-aliases/MenuProps.md)
- [Metric](type-aliases/Metric.md)
- [ModalProps](type-aliases/ModalProps.md)
- [NavListGroup](type-aliases/NavListGroup.md)
- [NavListItem](type-aliases/NavListItem.md)
- [NavListProps](type-aliases/NavListProps.md)
- [Notification](type-aliases/Notification.md)
- [NotificationAction](type-aliases/NotificationAction.md)
- [NotificationButtonProps](type-aliases/NotificationButtonProps.md)
- [NotificationCardProps](type-aliases/NotificationCardProps.md)
- [OAuthConsentLabels](type-aliases/OAuthConsentLabels.md)
- [OAuthConsentProps](type-aliases/OAuthConsentProps.md)
- [OnFilesChange](type-aliases/OnFilesChange.md)
- [OnRemove](type-aliases/OnRemove.md)
- [OnUpload](type-aliases/OnUpload.md)
- [OnUploadComplete](type-aliases/OnUploadComplete.md)
- [OnUploadError](type-aliases/OnUploadError.md)
- [OnUploadProgress](type-aliases/OnUploadProgress.md)
- [OnUploadStart](type-aliases/OnUploadStart.md)
- [SearchProps](type-aliases/SearchProps.md)
- [SpotlightCardProps](type-aliases/SpotlightCardProps.md)
- [UploadedFile](type-aliases/UploadedFile.md)
- [UploadResult](type-aliases/UploadResult.md)
## Variables
- [List](variables/List.md)
- [ListItem](variables/ListItem.md)
- [toast](variables/toast.md)
## Functions
- [Accordion](functions/Accordion.md)
- [collectGrantedScopes](functions/collectGrantedScopes.md)
- [DatePicker](functions/DatePicker.md)
- [Drawer](functions/Drawer.md)
- [EnhancedTitle](functions/EnhancedTitle.md)
- [FileUploader](functions/FileUploader.md)
- [InstallPwa](functions/InstallPwa.md)
- [InstallPwaUi](functions/InstallPwaUi.md)
- [LockedOverlay](functions/LockedOverlay.md)
- [Markdown](functions/Markdown.md)
- [Menu](functions/Menu.md)
- [MetricCard](functions/MetricCard.md)
- [Modal](functions/Modal.md)
- [NavList](functions/NavList.md)
- [NotificationButton](functions/NotificationButton.md)
- [NotificationCard](functions/NotificationCard.md)
- [NotificationsMenu](functions/NotificationsMenu.md)
- [OAuthConsent](functions/OAuthConsent.md)
- [Search](functions/Search.md)
- [SpotlightCard](functions/SpotlightCard.md)
- [Table](functions/Table.md)
- [Tabs](functions/Tabs.md)
- [ToastContainer](functions/ToastContainer.md)
---
## @ttoss/components(Components)
React components for the ttoss ecosystem. **ESM only** package.
## Quick Start
```shell
pnpm add @ttoss/components @ttoss/ui @emotion/react @ttoss/react-hooks
```
[View all components in Storybook](https://storybook.ttoss.dev/?path=/docs/components-accordion--docs)
## Components
All components are theme-aware and integrate seamlessly with `@ttoss/ui`.
### OAuthConsent
OAuth consent screen with flat and GitHub-style hierarchical scopes. Granting a parent scope automatically locks all descendants. All visible copy is injected via the `labels` prop — no hardcoded strings. [Docs](https://storybook.ttoss.dev/?path=/docs/components-oauthconsent--docs)
```tsx
{
const res = await authorize({ scopes: grantedScopes });
return { ok: res.ok };
}}
onAuthorized={() => {
window.location.href = resumeUrl;
}}
onDeny={() => navigate('/')}
labels={{
title: 'Authorize access',
requestedBy: (name) => (
<>
{name} is requesting access.
),
permissionsHeading: 'Requested permissions',
approve: 'Authorize',
deny: 'Deny',
invalidRequestTitle: 'Invalid request',
invalidRequestBody: 'Missing required OAuth parameters. Please try again.',
}}
/>;
```
### Accordion
Accessible accordion component with collapsible content sections. [Docs](https://storybook.ttoss.dev/?path=/docs/components-accordion--docs)
```tsx
({
from: subDays(new Date(), 7),
to: new Date(),
}),
},
]}
/>;
```
### Drawer
Slide-out panels from screen edges. [Docs](https://storybook.ttoss.dev/?path=/docs/components-drawer--docs)
```tsx
Drawer content
;
```
### EnhancedTitle
Structured title section with icon, badges, and metadata. [Docs](https://storybook.ttoss.dev/?path=/docs/components-enhancedtitle--docs)
```tsx
{
const result = await uploadToServer(file);
return { url: result.url, id: result.id, name: result.name };
}}
files={files}
onUploadComplete={(file, result) => setFiles([...files, result])}
onRemove={(file, index) => setFiles(files.filter((_, i) => i !== index))}
accept="image/*,.pdf"
maxSize={10 * 1024 * 1024}
maxFiles={5}
/>;
```
### InstallPwa
PWA installation prompt component.
```tsx
First item
Second item
;
```
### LockedOverlay
Block and display locked features or restricted content within a container. Unlike modals, overlays block only their parent container. [Docs](https://storybook.ttoss.dev/?path=/docs/components-lockedoverlay--docs)
```tsx
setIsOpen(false)}
header={{
icon: 'fluent:lock-closed-24-filled',
title: 'Premium Feature',
description: 'Available in Pro plan only',
variant: 'primary',
}}
actions={[
{
label: 'Upgrade Now',
icon: 'fluent-emoji-high-contrast:sparkles',
variant: 'primary',
onClick: handleUpgrade,
},
]}
>
This feature is only available for Pro users.
;
```
### Markdown
Render markdown content with theme integration. [Docs](https://storybook.ttoss.dev/?path=/docs/components-markdown--docs)
```tsx
;
```
### Menu
Floating dropdown panel with a configurable trigger icon. Use `NavList` as children for navigation items. [Docs](https://storybook.ttoss.dev/?path=/docs/components-menu--docs)
```tsx
;
// Custom trigger icon
;
```
### MetricCard
Display metrics with progress visualization, status indicators, and contextual information. [Docs](https://storybook.ttoss.dev/?path=/docs/components-metriccard--docs)
```tsx
setIsOpen(false)}
style={{ content: { backgroundColor: 'secondary' } }}
>
Modal content
;
```
### NotificationCard
Display notification messages with actions. [Docs](https://storybook.ttoss.dev/?path=/docs/components-notificationcard--docs)
```tsx
{}}
/>;
```
### NotificationsMenu
Menu component for displaying notifications. [Docs](https://storybook.ttoss.dev/?path=/docs/components-notificationsmenu--docs)
```tsx
{}}
/>;
```
### Search
Debounced search input with loading states. [Docs](https://storybook.ttoss.dev/?path=/docs/components-search--docs)
```tsx
Tab 1
Tab 2
Content 1
Content 2
;
```
### Toast
Toast notification system. [Docs](https://storybook.ttoss.dev/?path=/docs/components-toast--docs)
```tsx
setIsOpen(false)}
/>;
```
---
## Interface: BaseMetric
Defined in: [MetricCard/MetricCard.types.ts:6](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L6)
Base metric properties shared by all metric types.
## Extended by
- [`DateMetric`](DateMetric.md)
- [`PercentageMetric`](PercentageMetric.md)
- [`NumberMetric`](NumberMetric.md)
## Properties
### helpArticleAction?
> `optional` **helpArticleAction?**: () => `void`
Defined in: [MetricCard/MetricCard.types.ts:28](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L28)
Optional help article action handler.
#### Returns
`void`
***
### icon?
> `optional` **icon?**: `IconType`
Defined in: [MetricCard/MetricCard.types.ts:20](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L20)
Icon to display alongside the metric.
***
### label
> **label**: `string`
Defined in: [MetricCard/MetricCard.types.ts:10](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L10)
Label displayed above the metric value.
***
### onClick?
> `optional` **onClick?**: () => `void`
Defined in: [MetricCard/MetricCard.types.ts:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L24)
Optional click handler to make the metric card interactive.
#### Returns
`void`
***
### tooltip?
> `optional` **tooltip?**: `string` \| (() => `void`)
Defined in: [MetricCard/MetricCard.types.ts:16](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L16)
Optional tooltip text or action handler for additional context.
When a string is provided, it displays a simple tooltip.
When a function is provided, it's called when the tooltip icon is clicked.
---
## Interface: DateMetric
Defined in: [MetricCard/MetricCard.types.ts:34](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L34)
Date-based metric for displaying dates like expiration or renewal.
## Extends
- [`BaseMetric`](BaseMetric.md)
## Properties
### date
> **date**: `string`
Defined in: [MetricCard/MetricCard.types.ts:39](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L39)
The date value to display.
***
### helpArticleAction?
> `optional` **helpArticleAction?**: () => `void`
Defined in: [MetricCard/MetricCard.types.ts:28](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L28)
Optional help article action handler.
#### Returns
`void`
#### Inherited from
[`BaseMetric`](BaseMetric.md).[`helpArticleAction`](BaseMetric.md#helparticleaction)
***
### icon?
> `optional` **icon?**: `IconType`
Defined in: [MetricCard/MetricCard.types.ts:20](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L20)
Icon to display alongside the metric.
#### Inherited from
[`BaseMetric`](BaseMetric.md).[`icon`](BaseMetric.md#icon)
***
### isWarning?
> `optional` **isWarning?**: `boolean`
Defined in: [MetricCard/MetricCard.types.ts:47](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L47)
Whether to show a warning indicator.
***
### label
> **label**: `string`
Defined in: [MetricCard/MetricCard.types.ts:10](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L10)
Label displayed above the metric value.
#### Inherited from
[`BaseMetric`](BaseMetric.md).[`label`](BaseMetric.md#label)
***
### onClick?
> `optional` **onClick?**: () => `void`
Defined in: [MetricCard/MetricCard.types.ts:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L24)
Optional click handler to make the metric card interactive.
#### Returns
`void`
#### Inherited from
[`BaseMetric`](BaseMetric.md).[`onClick`](BaseMetric.md#onclick)
***
### remainingDaysMessage?
> `optional` **remainingDaysMessage?**: `string`
Defined in: [MetricCard/MetricCard.types.ts:43](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L43)
Optional message showing remaining days.
***
### tooltip?
> `optional` **tooltip?**: `string` \| (() => `void`)
Defined in: [MetricCard/MetricCard.types.ts:16](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L16)
Optional tooltip text or action handler for additional context.
When a string is provided, it displays a simple tooltip.
When a function is provided, it's called when the tooltip icon is clicked.
#### Inherited from
[`BaseMetric`](BaseMetric.md).[`tooltip`](BaseMetric.md#tooltip)
***
### type
> **type**: `"date"`
Defined in: [MetricCard/MetricCard.types.ts:35](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L35)
---
## Interface: DateRange
Defined in: [DatePicker/DatePicker.tsx:7](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/DatePicker/DatePicker.tsx#L7)
## Properties
### from
> **from**: `Date` \| `undefined`
Defined in: [DatePicker/DatePicker.tsx:8](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/DatePicker/DatePicker.tsx#L8)
***
### to
> **to**: `Date` \| `undefined`
Defined in: [DatePicker/DatePicker.tsx:9](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/DatePicker/DatePicker.tsx#L9)
---
## Interface: EnhancedTitleBadge
Defined in: [EnhancedTitle/EnhancedTitle.types.ts:20](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/EnhancedTitle/EnhancedTitle.types.ts#L20)
Badge configuration for top and bottom badge sections.
## Properties
### icon?
> `optional` **icon?**: `string`
Defined in: [EnhancedTitle/EnhancedTitle.types.ts:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/EnhancedTitle/EnhancedTitle.types.ts#L24)
Icon to display in the badge.
***
### label
> **label**: `string`
Defined in: [EnhancedTitle/EnhancedTitle.types.ts:28](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/EnhancedTitle/EnhancedTitle.types.ts#L28)
Badge label text.
***
### variant?
> `optional` **variant?**: `string`
Defined in: [EnhancedTitle/EnhancedTitle.types.ts:32](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/EnhancedTitle/EnhancedTitle.types.ts#L32)
Badge visual variant.
---
## Interface: EnhancedTitleProps
Defined in: [EnhancedTitle/EnhancedTitle.types.ts:38](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/EnhancedTitle/EnhancedTitle.types.ts#L38)
Props for the EnhancedTitle component.
## Properties
### bottomBadges?
> `optional` **bottomBadges?**: [`EnhancedTitleBadge`](EnhancedTitleBadge.md)[]
Defined in: [EnhancedTitle/EnhancedTitle.types.ts:67](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/EnhancedTitle/EnhancedTitle.types.ts#L67)
Badges to display below the title.
***
### description?
> `optional` **description?**: `string`
Defined in: [EnhancedTitle/EnhancedTitle.types.ts:55](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/EnhancedTitle/EnhancedTitle.types.ts#L55)
Optional subtitle/description text.
***
### frontTitle?
> `optional` **frontTitle?**: `string`
Defined in: [EnhancedTitle/EnhancedTitle.types.ts:59](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/EnhancedTitle/EnhancedTitle.types.ts#L59)
Optional text displayed next to the title (e.g., price, metadata).
***
### icon?
> `optional` **icon?**: `string`
Defined in: [EnhancedTitle/EnhancedTitle.types.ts:47](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/EnhancedTitle/EnhancedTitle.types.ts#L47)
Icon to display next to the title.
***
### title
> **title**: `string`
Defined in: [EnhancedTitle/EnhancedTitle.types.ts:51](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/EnhancedTitle/EnhancedTitle.types.ts#L51)
Main title text (heading).
***
### topBadges?
> `optional` **topBadges?**: [`EnhancedTitleBadge`](EnhancedTitleBadge.md)[]
Defined in: [EnhancedTitle/EnhancedTitle.types.ts:63](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/EnhancedTitle/EnhancedTitle.types.ts#L63)
Badges to display above the title.
***
### variant?
> `optional` **variant?**: [`EnhancedTitleVariant`](../type-aliases/EnhancedTitleVariant.md)
Defined in: [EnhancedTitle/EnhancedTitle.types.ts:43](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/EnhancedTitle/EnhancedTitle.types.ts#L43)
Visual variant for the icon wrapper.
#### Default
```ts
'primary'
```
---
## Interface: ListItemProps
Defined in: [List/ListItem.tsx:3](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/List/ListItem.tsx#L3)
## Extends
- `HTMLProps`\<`HTMLLIElement`\>
## Properties
### children
> **children**: `ReactNode`
Defined in: [List/ListItem.tsx:4](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/List/ListItem.tsx#L4)
#### Overrides
`React.HTMLProps.children`
---
## Interface: ListProps
Defined in: [List/List.tsx:3](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/List/List.tsx#L3)
## Extends
- `HTMLProps`\<`HTMLUListElement`\>
## Properties
### children
> **children**: `ReactNode`
Defined in: [List/List.tsx:4](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/List/List.tsx#L4)
#### Overrides
`React.HTMLProps.children`
---
## Interface: MetricCardProps
Defined in: [MetricCard/MetricCard.types.ts:104](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L104)
Props for the MetricCard component.
## Properties
### isLoading?
> `optional` **isLoading?**: `boolean`
Defined in: [MetricCard/MetricCard.types.ts:112](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L112)
Whether the card is in loading state.
***
### metric
> **metric**: [`Metric`](../type-aliases/Metric.md)
Defined in: [MetricCard/MetricCard.types.ts:108](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L108)
The metric configuration to display.
---
## Interface: NumberMetric
Defined in: [MetricCard/MetricCard.types.ts:76](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L76)
Number-based metric for displaying counts.
## Extends
- [`BaseMetric`](BaseMetric.md)
## Properties
### current
> **current**: `number`
Defined in: [MetricCard/MetricCard.types.ts:81](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L81)
Current value.
***
### footerText?
> `optional` **footerText?**: `string`
Defined in: [MetricCard/MetricCard.types.ts:93](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L93)
Optional footer text below the metric.
***
### formatValue?
> `optional` **formatValue?**: (`value`) => `string`
Defined in: [MetricCard/MetricCard.types.ts:89](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L89)
Custom formatter for displaying values.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `value` | `number` |
#### Returns
`string`
***
### helpArticleAction?
> `optional` **helpArticleAction?**: () => `void`
Defined in: [MetricCard/MetricCard.types.ts:28](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L28)
Optional help article action handler.
#### Returns
`void`
#### Inherited from
[`BaseMetric`](BaseMetric.md).[`helpArticleAction`](BaseMetric.md#helparticleaction)
***
### icon?
> `optional` **icon?**: `IconType`
Defined in: [MetricCard/MetricCard.types.ts:20](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L20)
Icon to display alongside the metric.
#### Inherited from
[`BaseMetric`](BaseMetric.md).[`icon`](BaseMetric.md#icon)
***
### label
> **label**: `string`
Defined in: [MetricCard/MetricCard.types.ts:10](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L10)
Label displayed above the metric value.
#### Inherited from
[`BaseMetric`](BaseMetric.md).[`label`](BaseMetric.md#label)
***
### max
> **max**: `number` \| `null`
Defined in: [MetricCard/MetricCard.types.ts:85](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L85)
Maximum value. Use null for unlimited.
***
### onClick?
> `optional` **onClick?**: () => `void`
Defined in: [MetricCard/MetricCard.types.ts:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L24)
Optional click handler to make the metric card interactive.
#### Returns
`void`
#### Inherited from
[`BaseMetric`](BaseMetric.md).[`onClick`](BaseMetric.md#onclick)
***
### tooltip?
> `optional` **tooltip?**: `string` \| (() => `void`)
Defined in: [MetricCard/MetricCard.types.ts:16](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L16)
Optional tooltip text or action handler for additional context.
When a string is provided, it displays a simple tooltip.
When a function is provided, it's called when the tooltip icon is clicked.
#### Inherited from
[`BaseMetric`](BaseMetric.md).[`tooltip`](BaseMetric.md#tooltip)
***
### type
> **type**: `"number"`
Defined in: [MetricCard/MetricCard.types.ts:77](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L77)
---
## Interface: PercentageMetric
Defined in: [MetricCard/MetricCard.types.ts:53](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L53)
Percentage-based metric with progress bar.
## Extends
- [`BaseMetric`](BaseMetric.md)
## Properties
### current
> **current**: `number`
Defined in: [MetricCard/MetricCard.types.ts:58](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L58)
Current value.
***
### formatValue?
> `optional` **formatValue?**: (`value`) => `string`
Defined in: [MetricCard/MetricCard.types.ts:66](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L66)
Custom formatter for displaying values.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `value` | `number` |
#### Returns
`string`
***
### helpArticleAction?
> `optional` **helpArticleAction?**: () => `void`
Defined in: [MetricCard/MetricCard.types.ts:28](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L28)
Optional help article action handler.
#### Returns
`void`
#### Inherited from
[`BaseMetric`](BaseMetric.md).[`helpArticleAction`](BaseMetric.md#helparticleaction)
***
### icon?
> `optional` **icon?**: `IconType`
Defined in: [MetricCard/MetricCard.types.ts:20](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L20)
Icon to display alongside the metric.
#### Inherited from
[`BaseMetric`](BaseMetric.md).[`icon`](BaseMetric.md#icon)
***
### label
> **label**: `string`
Defined in: [MetricCard/MetricCard.types.ts:10](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L10)
Label displayed above the metric value.
#### Inherited from
[`BaseMetric`](BaseMetric.md).[`label`](BaseMetric.md#label)
***
### max
> **max**: `number` \| `null`
Defined in: [MetricCard/MetricCard.types.ts:62](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L62)
Maximum value. Use null for unlimited.
***
### onClick?
> `optional` **onClick?**: () => `void`
Defined in: [MetricCard/MetricCard.types.ts:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L24)
Optional click handler to make the metric card interactive.
#### Returns
`void`
#### Inherited from
[`BaseMetric`](BaseMetric.md).[`onClick`](BaseMetric.md#onclick)
***
### showAlertThreshold?
> `optional` **showAlertThreshold?**: `number`
Defined in: [MetricCard/MetricCard.types.ts:70](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L70)
Percentage threshold at which to show an alert.
***
### tooltip?
> `optional` **tooltip?**: `string` \| (() => `void`)
Defined in: [MetricCard/MetricCard.types.ts:16](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L16)
Optional tooltip text or action handler for additional context.
When a string is provided, it displays a simple tooltip.
When a function is provided, it's called when the tooltip icon is clicked.
#### Inherited from
[`BaseMetric`](BaseMetric.md).[`tooltip`](BaseMetric.md#tooltip)
***
### type
> **type**: `"percentage"`
Defined in: [MetricCard/MetricCard.types.ts:54](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L54)
---
## Type Alias: AccordionItem
> **AccordionItem** = `object`
Defined in: [Accordion/Accordion.tsx:8](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Accordion/Accordion.tsx#L8)
Individual item for the Accordion component.
## Properties
### content
> **content**: `React.ReactNode`
Defined in: [Accordion/Accordion.tsx:21](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Accordion/Accordion.tsx#L21)
Content displayed when the accordion item is expanded.
***
### disabled?
> `optional` **disabled?**: `boolean`
Defined in: [Accordion/Accordion.tsx:26](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Accordion/Accordion.tsx#L26)
Whether the item is disabled.
#### Default
```ts
false
```
***
### id?
> `optional` **id?**: `string`
Defined in: [Accordion/Accordion.tsx:13](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Accordion/Accordion.tsx#L13)
Unique identifier for the accordion item.
If not provided, will use the index as the key.
***
### title
> **title**: `React.ReactNode`
Defined in: [Accordion/Accordion.tsx:17](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Accordion/Accordion.tsx#L17)
Title displayed in the accordion header.
---
## Type Alias: AccordionProps
> **AccordionProps** = `BoxProps` & `object`
Defined in: [Accordion/Accordion.tsx:62](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Accordion/Accordion.tsx#L62)
Props for the Accordion component.
## Type Declaration
### defaultExpanded?
> `optional` **defaultExpanded?**: `number` \| `number`[]
Index or array of indices for initially expanded items.
### items
> **items**: [`AccordionItem`](AccordionItem.md)[]
Array of accordion items to render.
### multiple?
> `optional` **multiple?**: `boolean`
Whether multiple items can be expanded at once.
#### Default
```ts
false
```
### onAccordionChange?
> `optional` **onAccordionChange?**: (`expandedIndices`) => `void`
Callback invoked when items are expanded or collapsed.
Receives array of currently expanded indices.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `expandedIndices` | `number`[] |
#### Returns
`void`
### renderItem?
> `optional` **renderItem?**: (`props`) => `React.ReactNode`
Custom render function for accordion items.
Provides full control over item rendering while maintaining accessibility.
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `props` | [`AccordionRenderItemProps`](AccordionRenderItemProps.md) |
#### Returns
`React.ReactNode`
---
## Type Alias: AccordionRenderItemProps
> **AccordionRenderItemProps** = `object`
Defined in: [Accordion/Accordion.tsx:32](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Accordion/Accordion.tsx#L32)
Render props for custom accordion item rendering.
## Properties
### ids
> **ids**: `object`
Defined in: [Accordion/Accordion.tsx:52](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Accordion/Accordion.tsx#L52)
Generated IDs for accessibility.
#### headingId
> **headingId**: `string`
#### itemId
> **itemId**: `string`
#### panelId
> **panelId**: `string`
***
### index
> **index**: `number`
Defined in: [Accordion/Accordion.tsx:40](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Accordion/Accordion.tsx#L40)
Index of the item in the items array.
***
### isExpanded
> **isExpanded**: `boolean`
Defined in: [Accordion/Accordion.tsx:44](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Accordion/Accordion.tsx#L44)
Whether the item is currently expanded.
***
### item
> **item**: [`AccordionItem`](AccordionItem.md)
Defined in: [Accordion/Accordion.tsx:36](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Accordion/Accordion.tsx#L36)
The accordion item data.
***
### toggle
> **toggle**: () => `void`
Defined in: [Accordion/Accordion.tsx:48](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Accordion/Accordion.tsx#L48)
Function to toggle the item's expanded state.
#### Returns
`void`
---
## Type Alias: ConsentScope
> **ConsentScope** = `object`
Defined in: [OAuthConsent/OAuthConsent.tsx:18](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/OAuthConsent/OAuthConsent.tsx#L18)
A single OAuth scope, optionally with implied child scopes.
## Properties
### children?
> `optional` **children?**: `ConsentScope`[]
Defined in: [OAuthConsent/OAuthConsent.tsx:29](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/OAuthConsent/OAuthConsent.tsx#L29)
Child scopes implied by this one. When this scope is granted, every
descendant is granted and locked (checked + disabled).
***
### defaultGranted?
> `optional` **defaultGranted?**: `boolean`
Defined in: [OAuthConsent/OAuthConsent.tsx:34](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/OAuthConsent/OAuthConsent.tsx#L34)
Pre-checked on mount.
#### Default
```ts
false
```
***
### description
> **description**: `string`
Defined in: [OAuthConsent/OAuthConsent.tsx:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/OAuthConsent/OAuthConsent.tsx#L24)
Scope description shown below the label. Pre-translated by the consumer.
***
### key
> **key**: `string`
Defined in: [OAuthConsent/OAuthConsent.tsx:20](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/OAuthConsent/OAuthConsent.tsx#L20)
OAuth scope token, e.g. 'repo', 'write:packages', 'read'.
***
### label
> **label**: `string`
Defined in: [OAuthConsent/OAuthConsent.tsx:22](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/OAuthConsent/OAuthConsent.tsx#L22)
Bold display name shown on the left. Pre-translated by the consumer.
***
### required?
> `optional` **required?**: `boolean`
Defined in: [OAuthConsent/OAuthConsent.tsx:39](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/OAuthConsent/OAuthConsent.tsx#L39)
Always granted; cannot be unchecked. Renders checked + disabled.
#### Default
```ts
false
```
---
## Type Alias: DrawerProps
> **DrawerProps** = `DrawerUiProps` & `object`
Defined in: [Drawer/Drawer.tsx:7](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Drawer/Drawer.tsx#L7)
## Type Declaration
### sx?
> `optional` **sx?**: `BoxProps`\[`"sx"`\]
---
## Type Alias: EnhancedTitleVariant
> **EnhancedTitleVariant** = `"spotlight-accent"` \| `"spotlight-primary"` \| `"primary"` \| `"secondary"` \| `"accent"` \| `"positive"` \| `"negative"` \| `"informative"` \| `"muted"`
Defined in: [EnhancedTitle/EnhancedTitle.types.ts:6](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/EnhancedTitle/EnhancedTitle.types.ts#L6)
Visual variant for the icon wrapper.
---
## Type Alias: FileUploadState
> **FileUploadState** = `object`
Defined in: [FileUploader/FileUploader.tsx:10](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L10)
## Properties
### error?
> `optional` **error?**: `Error`
Defined in: [FileUploader/FileUploader.tsx:15](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L15)
***
### file
> **file**: `File`
Defined in: [FileUploader/FileUploader.tsx:11](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L11)
***
### progress?
> `optional` **progress?**: `number`
Defined in: [FileUploader/FileUploader.tsx:13](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L13)
***
### result?
> `optional` **result?**: [`UploadResult`](UploadResult.md)
Defined in: [FileUploader/FileUploader.tsx:14](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L14)
***
### status
> **status**: `"pending"` \| `"uploading"` \| `"completed"` \| `"error"`
Defined in: [FileUploader/FileUploader.tsx:12](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L12)
---
## Type Alias: FileUploaderProps
> **FileUploaderProps** = `object`
Defined in: [FileUploader/FileUploader.tsx:37](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L37)
## Properties
### accept?
> `optional` **accept?**: `string`
Defined in: [FileUploader/FileUploader.tsx:50](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L50)
***
### autoUpload?
> `optional` **autoUpload?**: `boolean`
Defined in: [FileUploader/FileUploader.tsx:57](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L57)
***
### children?
> `optional` **children?**: `React.ReactNode`
Defined in: [FileUploader/FileUploader.tsx:63](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L63)
***
### disabled?
> `optional` **disabled?**: `boolean`
Defined in: [FileUploader/FileUploader.tsx:54](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L54)
***
### error?
> `optional` **error?**: `string`
Defined in: [FileUploader/FileUploader.tsx:62](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L62)
***
### FileListComponent?
> `optional` **FileListComponent?**: (`props`) => `React.ReactNode`
Defined in: [FileUploader/FileUploader.tsx:65](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L65)
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `props` | \{ `files`: [`UploadedFile`](UploadedFile.md)[]; `onRemove`: (`index`) => `void`; \} |
| `props.files` | [`UploadedFile`](UploadedFile.md)[] |
| `props.onRemove` | (`index`) => `void` |
#### Returns
`React.ReactNode`
***
### files?
> `optional` **files?**: [`UploadedFile`](UploadedFile.md)[]
Defined in: [FileUploader/FileUploader.tsx:71](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L71)
***
### maxFiles?
> `optional` **maxFiles?**: `number`
Defined in: [FileUploader/FileUploader.tsx:53](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L53)
***
### maxSize?
> `optional` **maxSize?**: `number`
Defined in: [FileUploader/FileUploader.tsx:52](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L52)
***
### multiple?
> `optional` **multiple?**: `boolean`
Defined in: [FileUploader/FileUploader.tsx:51](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L51)
***
### onFilesChange?
> `optional` **onFilesChange?**: [`OnFilesChange`](OnFilesChange.md)
Defined in: [FileUploader/FileUploader.tsx:46](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L46)
***
### onRemove?
> `optional` **onRemove?**: [`OnRemove`](OnRemove.md)
Defined in: [FileUploader/FileUploader.tsx:47](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L47)
***
### onUpload
> **onUpload**: [`OnUpload`](OnUpload.md)
Defined in: [FileUploader/FileUploader.tsx:39](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L39)
***
### onUploadComplete?
> `optional` **onUploadComplete?**: [`OnUploadComplete`](OnUploadComplete.md)
Defined in: [FileUploader/FileUploader.tsx:44](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L44)
***
### onUploadError?
> `optional` **onUploadError?**: [`OnUploadError`](OnUploadError.md)
Defined in: [FileUploader/FileUploader.tsx:45](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L45)
***
### onUploadProgress?
> `optional` **onUploadProgress?**: [`OnUploadProgress`](OnUploadProgress.md)
Defined in: [FileUploader/FileUploader.tsx:43](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L43)
***
### onUploadStart?
> `optional` **onUploadStart?**: [`OnUploadStart`](OnUploadStart.md)
Defined in: [FileUploader/FileUploader.tsx:42](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L42)
***
### placeholder?
> `optional` **placeholder?**: `string`
Defined in: [FileUploader/FileUploader.tsx:61](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L61)
***
### retryAttempts?
> `optional` **retryAttempts?**: `number`
Defined in: [FileUploader/FileUploader.tsx:58](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L58)
***
### showFileList?
> `optional` **showFileList?**: `boolean`
Defined in: [FileUploader/FileUploader.tsx:64](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/FileUploader/FileUploader.tsx#L64)
---
## Type Alias: InstallPwaUiProps
> **InstallPwaUiProps** = `object`
Defined in: [InstallPwa/InstallPwa.tsx:6](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/InstallPwa/InstallPwa.tsx#L6)
## Properties
### onInstall
> **onInstall**: `React.MouseEventHandler`\<`HTMLButtonElement`\>
Defined in: [InstallPwa/InstallPwa.tsx:7](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/InstallPwa/InstallPwa.tsx#L7)
---
## Type Alias: LinkComponentProps
> **LinkComponentProps** = `object`
Defined in: [NavList/NavList.tsx:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L24)
## Indexable
> \[`key`: `string`\]: `unknown`
## Properties
### children
> **children**: `React.ReactNode`
Defined in: [NavList/NavList.tsx:27](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L27)
***
### href
> **href**: `string`
Defined in: [NavList/NavList.tsx:25](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L25)
***
### onClick?
> `optional` **onClick?**: (`event`) => `void`
Defined in: [NavList/NavList.tsx:26](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L26)
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `event` | `React.MouseEvent`\<`HTMLAnchorElement`\> |
#### Returns
`void`
---
## Type Alias: MarkdownProps
> **MarkdownProps** = `Options` & `object`
Defined in: [Markdown/Markdown.tsx:8](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Markdown/Markdown.tsx#L8)
## Type Declaration
### children
> **children**: `string`
### sx?
> `optional` **sx?**: `FlexProps`\[`"sx"`\]
---
## Type Alias: MenuProps
> **MenuProps** = `object`
Defined in: [Menu/Menu.tsx:5](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Menu/Menu.tsx#L5)
## Properties
### children
> **children**: `React.ReactNode`
Defined in: [Menu/Menu.tsx:6](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Menu/Menu.tsx#L6)
***
### menuIcon?
> `optional` **menuIcon?**: `string`
Defined in: [Menu/Menu.tsx:8](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Menu/Menu.tsx#L8)
***
### sx?
> `optional` **sx?**: `Record`\<`string`, `unknown`\>
Defined in: [Menu/Menu.tsx:7](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Menu/Menu.tsx#L7)
---
## Type Alias: Metric
> **Metric** = [`DateMetric`](../interfaces/DateMetric.md) \| [`PercentageMetric`](../interfaces/PercentageMetric.md) \| [`NumberMetric`](../interfaces/NumberMetric.md)
Defined in: [MetricCard/MetricCard.types.ts:99](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/MetricCard/MetricCard.types.ts#L99)
Union type for all supported metric types.
---
## Type Alias: ModalProps
> **ModalProps** = `ReactModal.Props`
Defined in: [Modal/Modal.tsx:10](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/Modal/Modal.tsx#L10)
---
## Type Alias: NavListGroup
> **NavListGroup** = `object`
Defined in: [NavList/NavList.tsx:17](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L17)
## Properties
### divider?
> `optional` **divider?**: `boolean`
Defined in: [NavList/NavList.tsx:21](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L21)
***
### id?
> `optional` **id?**: `string`
Defined in: [NavList/NavList.tsx:18](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L18)
***
### items
> **items**: [`NavListItem`](NavListItem.md)[]
Defined in: [NavList/NavList.tsx:20](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L20)
***
### label?
> `optional` **label?**: `string`
Defined in: [NavList/NavList.tsx:19](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L19)
---
## Type Alias: NavListItem
> **NavListItem** = `object`
Defined in: [NavList/NavList.tsx:5](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L5)
## Properties
### active?
> `optional` **active?**: `boolean`
Defined in: [NavList/NavList.tsx:11](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L11)
***
### disabled?
> `optional` **disabled?**: `boolean`
Defined in: [NavList/NavList.tsx:10](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L10)
***
### divider?
> `optional` **divider?**: `boolean`
Defined in: [NavList/NavList.tsx:14](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L14)
***
### group?
> `optional` **group?**: `string`
Defined in: [NavList/NavList.tsx:13](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L13)
***
### href
> **href**: `string`
Defined in: [NavList/NavList.tsx:8](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L8)
***
### icon?
> `optional` **icon?**: `string`
Defined in: [NavList/NavList.tsx:9](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L9)
***
### id?
> `optional` **id?**: `string`
Defined in: [NavList/NavList.tsx:6](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L6)
***
### label
> **label**: `string`
Defined in: [NavList/NavList.tsx:7](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L7)
***
### onClick?
> `optional` **onClick?**: (`event`) => `void`
Defined in: [NavList/NavList.tsx:12](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L12)
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `event` | `React.MouseEvent`\<`HTMLAnchorElement`\> |
#### Returns
`void`
---
## Type Alias: NavListProps
> **NavListProps** = `object`
Defined in: [NavList/NavList.tsx:31](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L31)
## Properties
### groups?
> `optional` **groups?**: [`NavListGroup`](NavListGroup.md)[]
Defined in: [NavList/NavList.tsx:33](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L33)
***
### iconSize?
> `optional` **iconSize?**: `number`
Defined in: [NavList/NavList.tsx:37](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L37)
***
### items?
> `optional` **items?**: [`NavListItem`](NavListItem.md)[]
Defined in: [NavList/NavList.tsx:32](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L32)
***
### LinkComponent?
> `optional` **LinkComponent?**: `React.ComponentType`\<[`LinkComponentProps`](LinkComponentProps.md)\>
Defined in: [NavList/NavList.tsx:52](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/components/src/components/NavList/NavList.tsx#L52)
Custom Link component to use for rendering links.
Useful for integrating with Next.js Link, React Router Link, etc.
#### Examples
```ts
// Next.js
> **MultistepFormProps**\<`FormValues`\> = `object`
Defined in: [packages/forms/src/MultistepForm/MultistepForm.tsx:22](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/MultistepForm/MultistepForm.tsx#L22)
## Type Parameters
| Type Parameter | Default type |
| ------ | ------ |
| `FormValues` | `unknown` |
## Properties
### footer?
> `optional` **footer?**: `string`
Defined in: [packages/forms/src/MultistepForm/MultistepForm.tsx:25](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/MultistepForm/MultistepForm.tsx#L25)
***
### header
> **header**: `MultistepHeaderProps`
Defined in: [packages/forms/src/MultistepForm/MultistepForm.tsx:23](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/MultistepForm/MultistepForm.tsx#L23)
***
### nextStepButtonLabel?
> `optional` **nextStepButtonLabel?**: `string`
Defined in: [packages/forms/src/MultistepForm/MultistepForm.tsx:27](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/MultistepForm/MultistepForm.tsx#L27)
***
### onSubmit
> **onSubmit**: (`data`) => `void`
Defined in: [packages/forms/src/MultistepForm/MultistepForm.tsx:26](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/MultistepForm/MultistepForm.tsx#L26)
#### Parameters
| Parameter | Type |
| ------ | ------ |
| `data` | `FormValues` |
#### Returns
`void`
***
### steps
> **steps**: `MultistepStep`[]
Defined in: [packages/forms/src/MultistepForm/MultistepForm.tsx:24](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/MultistepForm/MultistepForm.tsx#L24)
***
### submitButtonLabel?
> `optional` **submitButtonLabel?**: `string`
Defined in: [packages/forms/src/MultistepForm/MultistepForm.tsx:28](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/MultistepForm/MultistepForm.tsx#L28)
---
## Function: FormActions()
> **FormActions**(`__namedParameters`): `Element`
Defined in: [packages/forms/src/FormActions.tsx:46](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormActions.tsx#L46)
FormActions is a layout container for form action buttons such as Submit,
Cancel, and Reset. It renders a flex row with consistent spacing.
Use `align` to control horizontal button placement (`'left'`, `'center'`,
or `'right'`). Use `sticky` to keep the action bar visible while the user
scrolls through a long form.
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | [`FormActionsProps`](../type-aliases/FormActionsProps.md) |
## Returns
`Element`
## Example
```tsx
Cancel
Save
```
---
## Function: FormErrorMessage()
> **FormErrorMessage**\<`TFieldValues`\>(`__namedParameters`): `Element`
Defined in: [packages/forms/src/FormErrorMessage.tsx:21](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormErrorMessage.tsx#L21)
## Type Parameters
| Type Parameter | Default type |
| ------ | ------ |
| `TFieldValues` *extends* `FieldValues` | `FieldValues` |
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | \{ `disabled?`: `boolean`; `name`: `FieldName`\<`TFieldValues`\>; \} |
| `__namedParameters.disabled?` | `boolean` |
| `__namedParameters.name` | `FieldName`\<`TFieldValues`\> |
## Returns
`Element`
---
## Function: FormField()
> **FormField**\<`TFieldValues`, `TName`\>(`__namedParameters`): `Element`
Defined in: [packages/forms/src/FormField.tsx:65](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormField.tsx#L65)
## Type Parameters
| Type Parameter | Default type |
| ------ | ------ |
| `TFieldValues` *extends* `FieldValues` | `FieldValues` |
| `TName` *extends* `string` | `FieldPath`\<`TFieldValues`\> |
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | `FormFieldCompleteProps`\<`TFieldValues`, `TName`\> |
## Returns
`Element`
---
## Function: FormFieldCheckbox()
> **FormFieldCheckbox**\<`TFieldValues`, `TName`\>(`__namedParameters`): `Element`
Defined in: [packages/forms/src/FormFieldCheckbox.tsx:13](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldCheckbox.tsx#L13)
## Type Parameters
| Type Parameter | Default type |
| ------ | ------ |
| `TFieldValues` *extends* `FieldValues` | `FieldValues` |
| `TName` *extends* `string` | `FieldPath`\<`TFieldValues`\> |
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | `FormFieldCheckboxProps`\<`TFieldValues`, `TName`\> |
## Returns
`Element`
---
## Function: FormFieldCreditCardNumber()
> **FormFieldCreditCardNumber**\<`TFieldValues`, `TName`\>(`__namedParameters`): `Element`
Defined in: [packages/forms/src/FormFieldCreditCardNumber.tsx:13](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldCreditCardNumber.tsx#L13)
## Type Parameters
| Type Parameter | Default type |
| ------ | ------ |
| `TFieldValues` *extends* `FieldValues` | `FieldValues` |
| `TName` *extends* `string` | `FieldPath`\<`TFieldValues`\> |
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | `FormFieldCreditCardNumberProps`\<`TFieldValues`, `TName`\> |
## Returns
`Element`
---
## Function: FormFieldCurrencyInput()
> **FormFieldCurrencyInput**\<`TFieldValues`, `TName`\>(`__namedParameters`): `Element`
Defined in: [packages/forms/src/FormFieldCurrencyInput.tsx:15](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldCurrencyInput.tsx#L15)
## Type Parameters
| Type Parameter | Default type |
| ------ | ------ |
| `TFieldValues` *extends* `FieldValues` | `FieldValues` |
| `TName` *extends* `string` | `FieldPath`\<`TFieldValues`\> |
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | `FormFieldCurrencyInputProps`\<`TFieldValues`, `TName`\> |
## Returns
`Element`
---
## Function: FormFieldDatePicker()
> **FormFieldDatePicker**\<`TFieldValues`, `TName`\>(`__namedParameters`): `Element`
Defined in: [packages/forms/src/FormFieldDatePicker.tsx:18](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldDatePicker.tsx#L18)
## Type Parameters
| Type Parameter | Default type |
| ------ | ------ |
| `TFieldValues` *extends* `FieldValues` | `FieldValues` |
| `TName` *extends* `string` | `FieldPath`\<`TFieldValues`\> |
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | `FormFieldDatePickerProps`\<`TFieldValues`, `TName`\> |
## Returns
`Element`
---
## Function: FormFieldInput()
> **FormFieldInput**\<`TFieldValues`, `TName`\>(`__namedParameters`): `Element`
Defined in: [packages/forms/src/FormFieldInput.tsx:11](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldInput.tsx#L11)
## Type Parameters
| Type Parameter | Default type |
| ------ | ------ |
| `TFieldValues` *extends* `FieldValues` | `FieldValues` |
| `TName` *extends* `string` | `FieldPath`\<`TFieldValues`\> |
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | `FormFieldInputProps`\<`TFieldValues`, `TName`\> |
## Returns
`Element`
---
## Function: FormFieldNumericFormat()
> **FormFieldNumericFormat**\<`TFieldValues`, `TName`\>(`__namedParameters`): `Element`
Defined in: [packages/forms/src/FormFieldNumericFormat.tsx:30](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldNumericFormat.tsx#L30)
## Type Parameters
| Type Parameter | Default type |
| ------ | ------ |
| `TFieldValues` *extends* `FieldValues` | `FieldValues` |
| `TName` *extends* `string` | `FieldPath`\<`TFieldValues`\> |
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | `FormFieldNumericFormatProps`\<`TFieldValues`, `TName`\> |
## Returns
`Element`
---
## Function: FormFieldPassword()
> **FormFieldPassword**\<`TFieldValues`, `TName`\>(`__namedParameters`): `Element`
Defined in: [packages/forms/src/FormFieldPassword.tsx:11](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldPassword.tsx#L11)
## Type Parameters
| Type Parameter | Default type |
| ------ | ------ |
| `TFieldValues` *extends* `FieldValues` | `FieldValues` |
| `TName` *extends* `string` | `FieldPath`\<`TFieldValues`\> |
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | `FormFieldPasswordProps`\<`TFieldValues`, `TName`\> |
## Returns
`Element`
---
## Function: FormFieldPatternFormat()
> **FormFieldPatternFormat**\<`TFieldValues`, `TName`\>(`__namedParameters`): `Element`
Defined in: [packages/forms/src/FormFieldPatternFormat.tsx:15](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldPatternFormat.tsx#L15)
## Type Parameters
| Type Parameter | Default type |
| ------ | ------ |
| `TFieldValues` *extends* `FieldValues` | `FieldValues` |
| `TName` *extends* `string` | `FieldPath`\<`TFieldValues`\> |
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | `FormFieldPatternFormatProps`\<`TFieldValues`, `TName`\> |
## Returns
`Element`
---
## Function: FormFieldPhone()(Functions)
> **FormFieldPhone**\<`TFieldValues`, `TName`\>(`__namedParameters`): `Element`
Defined in: [packages/forms/src/FormFieldPhone.tsx:233](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldPhone.tsx#L233)
Generic phone number form field that supports an optional country code prefix.
By default, a country-code dropdown is rendered using `COMMON_PHONE_COUNTRY_CODES`
(15 common countries + a Manual entry; Manual is the first entry at index 0).
Pass `countryCodeOptions={[]}` to disable the dropdown and show a plain phone input.
The format prop defines the pattern for the local phone number (using #
as digit placeholders). When a countryCode is provided it is prepended to
the format and rendered as a read-only literal inside the input.
When the user selects the "Manual" option (`MANUAL_PHONE_COUNTRY_CODE`),
the pattern mask is disabled and a plain text input is shown so the user
can type the full international number freely.
When a country code is provided, the stored value is the country code
concatenated directly with the raw local digits (e.g., `"+15555555555"`
for country code `"+1"` and local digits `"5555555555"`). When no country
code is set, only the raw local digits are stored.
Changing the country code via the dropdown automatically resets the phone
number field to an empty string, so a new number can be entered in the
correct format for the selected country.
## Type Parameters
| Type Parameter | Default type |
| ------ | ------ |
| `TFieldValues` *extends* `FieldValues` | `FieldValues` |
| `TName` *extends* `string` | `FieldPath`\<`TFieldValues`\> |
## Parameters
| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | [`FormFieldPhoneProps`](../type-aliases/FormFieldPhoneProps.md)\<`TFieldValues`, `TName`\> |
## Returns
`Element`
## Examples
```tsx
// Default: dropdown with COMMON_PHONE_COUNTRY_CODES, country code managed internally.
// The submitted value includes the country code prefix (e.g. '+15555555555').
console.log('selected', code)}
/>
```
```tsx
// No dropdown — plain phone input; value includes the prefix.
// e.g. { phone: '+15555555555' }
value.length > 10 ? '(##) #####-####' : '(##) ####-#####'
}
countryCodeOptions={[]}
/>
```
```tsx
// Store the selected country code as a separate form field.
// Submitted data: { phone: '+15555555555', countryCode: '+1' }
```
// Show a group-level validation error (e.g. for an array field)
```tsx
{fields.map((field, i) => (
```
---
## Function: useFormGroup()
> **useFormGroup**(): `object`
Defined in: [packages/forms/src/FormGroup.tsx:13](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormGroup.tsx#L13)
## Returns
### level
> **level**: `number` \| `undefined` = `parentLevel`
### ~~levelsLength~~
> **levelsLength**: `number` \| `undefined`
#### Deprecated
`levelsLength` has been removed from `FormGroup` internals.
This field always returns `undefined`. Use `level` to determine nesting depth.
---
## index(4)
## Modules
- [yup](yup/index.md)
- [zod](zod/index.md)
## Interfaces
- [DateRangePreset](interfaces/DateRangePreset.md)
## Type Aliases
- [CountryCodeOption](type-aliases/CountryCodeOption.md)
- [FormActionsProps](type-aliases/FormActionsProps.md)
- [FormFieldPhoneProps](type-aliases/FormFieldPhoneProps.md)
- [FormFieldProps](type-aliases/FormFieldProps.md)
- [FormRadioOption](type-aliases/FormRadioOption.md)
## Variables
- [COMMON\_PHONE\_COUNTRY\_CODES](variables/COMMON_PHONE_COUNTRY_CODES.md)
- [Form](variables/Form.md)
- [MANUAL\_PHONE\_COUNTRY\_CODE](variables/MANUAL_PHONE_COUNTRY_CODE.md)
## Functions
- [FormActions](functions/FormActions.md)
- [FormErrorMessage](functions/FormErrorMessage.md)
- [FormField](functions/FormField.md)
- [FormFieldCheckbox](functions/FormFieldCheckbox.md)
- [FormFieldCreditCardNumber](functions/FormFieldCreditCardNumber.md)
- [FormFieldCurrencyInput](functions/FormFieldCurrencyInput.md)
- [FormFieldDatePicker](functions/FormFieldDatePicker.md)
- [FormFieldInput](functions/FormFieldInput.md)
- [FormFieldNumericFormat](functions/FormFieldNumericFormat.md)
- [FormFieldPassword](functions/FormFieldPassword.md)
- [FormFieldPatternFormat](functions/FormFieldPatternFormat.md)
- [FormFieldPhone](functions/FormFieldPhone.md)
- [FormFieldRadio](functions/FormFieldRadio.md)
- [FormFieldRadioCard](functions/FormFieldRadioCard.md)
- [FormFieldRadioCardIcony](functions/FormFieldRadioCardIcony.md)
- [FormFieldSegmentedControl](functions/FormFieldSegmentedControl.md)
- [FormFieldSelect](functions/FormFieldSelect.md)
- [FormFieldSwitch](functions/FormFieldSwitch.md)
- [FormFieldTextarea](functions/FormFieldTextarea.md)
- [FormGroup](functions/FormGroup.md)
- [useFormGroup](functions/useFormGroup.md)
---
## Interface: DateRangePreset
Defined in: [packages/forms/src/FormFieldDatePicker.tsx:6](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldDatePicker.tsx#L6)
## Properties
### getValue
> **getValue**: () => `DateRange`
Defined in: [packages/forms/src/FormFieldDatePicker.tsx:8](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldDatePicker.tsx#L8)
#### Returns
`DateRange`
***
### label
> **label**: `string`
Defined in: [packages/forms/src/FormFieldDatePicker.tsx:7](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldDatePicker.tsx#L7)
---
## Type Alias: CountryCodeOption
> **CountryCodeOption** = `object`
Defined in: [packages/forms/src/phoneCountryCodes.ts:28](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/phoneCountryCodes.ts#L28)
A curated list of the most common country calling codes paired with their
typical local phone number format patterns (using `#` as digit placeholders).
Import this constant and pass it to the `countryCodeOptions` prop of
`FormFieldPhone` to give users a ready-made country-code picker that also
automatically updates the number format when they switch countries.
## Example
```tsx
// COMMON_PHONE_COUNTRY_CODES is the default — no need to pass it explicitly.
// Index 0 is the "Manual" entry; index 1 is US (+1).
const [countryCode, setCountryCode] = React.useState(
COMMON_PHONE_COUNTRY_CODES[1].value // '+1'
);
> **FormFieldPhoneProps**\<`TFieldValues`, `TName`\> = [`FormFieldProps`](FormFieldProps.md)\<`TFieldValues`, `TName`\> & `Omit`\<`PatternFormatProps`, `"name"` \| `"format"`\> & `object`
Defined in: [packages/forms/src/FormFieldPhone.tsx:92](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldPhone.tsx#L92)
## Type Declaration
### countryCodeName?
> `optional` **countryCodeName?**: `string`
When provided, the selected country code is stored as a separate field
in the form under this name (e.g. `'countryCode'`). This allows the
submitted form data to include both the full phone value and the
selected calling code independently.
#### Example
```tsx
// Form data: { phone: '+15555555555', countryCode: '+1' }
> **FormFieldProps**\<`TFieldValues`, `TName`\> = `object` & `SxProp`
Defined in: [packages/forms/src/FormField.tsx:34](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormField.tsx#L34)
## Type Declaration
### auxiliaryCheckbox?
> `optional` **auxiliaryCheckbox?**: `AuxiliaryCheckboxProps`\<`TFieldValues`, `FieldPath`\<`TFieldValues`\>\>
Optional auxiliary checkbox to render between the field and error message.
Useful for input confirmation or conditional display of other fields.
### defaultValue?
> `optional` **defaultValue?**: `FieldPathValue`\<`TFieldValues`, `TName`\>
### disabled?
> `optional` **disabled?**: `boolean`
### id?
> `optional` **id?**: `string`
### label?
> `optional` **label?**: `React.ReactNode`
### labelTooltip?
> `optional` **labelTooltip?**: `TooltipProps`
### name
> **name**: `TName`
### rules?
> `optional` **rules?**: `Rules`\<`TFieldValues`, `TName`\>
### warning?
> `optional` **warning?**: `string` \| `React.ReactNode`
## Type Parameters
| Type Parameter | Default type |
| ------ | ------ |
| `TFieldValues` *extends* `FieldValues` | `FieldValues` |
| `TName` *extends* `FieldPath`\<`TFieldValues`\> | `FieldPath`\<`TFieldValues`\> |
---
## Type Alias: FormRadioOption
> **FormRadioOption** = `object`
Defined in: [packages/forms/src/FormFieldRadioCardIcony.tsx:7](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldRadioCardIcony.tsx#L7)
## Properties
### description?
> `optional` **description?**: `string`
Defined in: [packages/forms/src/FormFieldRadioCardIcony.tsx:10](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldRadioCardIcony.tsx#L10)
***
### icon?
> `optional` **icon?**: `React.ComponentType`\<\{ `className?`: `string`; `size?`: `number`; \}\>
Defined in: [packages/forms/src/FormFieldRadioCardIcony.tsx:11](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldRadioCardIcony.tsx#L11)
***
### label
> **label**: `string`
Defined in: [packages/forms/src/FormFieldRadioCardIcony.tsx:9](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldRadioCardIcony.tsx#L9)
***
### tag?
> `optional` **tag?**: `object`
Defined in: [packages/forms/src/FormFieldRadioCardIcony.tsx:12](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldRadioCardIcony.tsx#L12)
#### label
> **label**: `string`
#### sx?
> `optional` **sx?**: `ThemeUIStyleObject`
#### variant?
> `optional` **variant?**: `"accent"` \| `"positive"` \| `"caution"` \| `"muted"` \| `"negative"` \| `"primary"` \| `"secondary"` \| `"default"`
***
### value
> **value**: `string` \| `number`
Defined in: [packages/forms/src/FormFieldRadioCardIcony.tsx:8](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/FormFieldRadioCardIcony.tsx#L8)
---
## Variable: COMMON\_PHONE\_COUNTRY\_CODES
> `const` **COMMON\_PHONE\_COUNTRY\_CODES**: [`CountryCodeOption`](../type-aliases/CountryCodeOption.md)[]
Defined in: [packages/forms/src/phoneCountryCodes.ts:53](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/phoneCountryCodes.ts#L53)
Common country calling codes sorted by numeric dial-code order.
The "Manual" option is listed first, allowing users to type the full
international number freely without any mask.
---
## Variable: Form
> `const` **Form**: \<`TFieldValues`, `TContext`, `TTransformedValues`\>(`__namedParameters`) => `Element` & `object`
Defined in: [packages/forms/src/Form.tsx:65](https://github.com/ttoss/ttoss/blob/68af42ad6021a9e3ce38ea522772b004e09c3bbe/packages/forms/src/Form.tsx#L65)
Form is the root component for all form compositions. It wraps
`react-hook-form`'s `FormProvider` and an HTML `