frontend-patterns/canon/FrontendPatternLanguage.md

# Frontend Pattern Language

## 1. Premise

Frontend architecture is best understood as a progression of design decisions made under interacting forces.

Frameworks and named architectural styles are downstream manifestations of these decisions.

The pattern language therefore models:

1. the **context** in which a problem occurs,
2. the **forces** that make the problem non-trivial,
3. the **pattern** that resolves those forces,
4. the **resulting context** created by the resolution,
5. the **relations** to other patterns,
6. the **known implementations** of the pattern.

## 2. Fundamental responsibilities

The initial model uses the following responsibilities.

### Address

How application state, resources, views or intents are named and revisited.

Examples:

- URL,
- route,
- document identifier,
- workspace identifier,
- command target.

### Authority

Which copy or system is allowed to define truth.

Examples:

- server authority,
- local authority,
- replicated authority,
- event-log authority.

### Projection

How authoritative or selected information becomes perceivable frontend state.

Examples:

- server-rendered HTML,
- client-rendered view,
- streamed projection,
- static projection.

### Affordance

Immediate local state and behavior that makes interaction responsive and intelligible.

Examples:

- open/closed state,
- focus state,
- draft input,
- pending feedback,
- speculative UI.

### Mutation

How user intent becomes a proposed or committed state change.

### Synchronization

How separated copies discover and exchange changes.

### Reconciliation

How conflicting, stale or concurrent observations and mutations are resolved.

### Composition

How independently understandable pieces combine into a larger frontend.

### Execution

Where and when computation occurs.

Examples:

- build time,
- server,
- edge,
- browser,
- worker,
- device.

## 3. Relation to the Navigation → Content → Affordance model

The useful decomposition proposed by Ryan Carniato can be interpreted as:

```text
Navigation ≈ Address + mutation orchestration
Content    ≈ Authority → Projection
Affordance ≈ local interaction + speculative state
```

This is a powerful projection for server-authoritative web applications.

The broader language keeps authority independent so that local-first, peer-to-peer and replicated architectures can be represented without distortion.

## 4. Pattern families

Initial families:

- `authority`
- `address`
- `projection`
- `affordance`
- `mutation`
- `synchronization`
- `composition`
- `execution`
- `quality`

Families are navigational aids, not the primary ontology.

Patterns may participate in several families.

## 5. Pattern scales

The initial scale model is:

```text
L0 Experience / Product
L1 Application Topology
L2 Authority & Distribution
L3 Navigation & Projection
L4 Feature / Domain Boundaries
L5 Components
L6 Interaction & State
L7 Elements / Implementation
```

The scale prevents unlike patterns from being compared as peers.

## 6. Generative use

The language should support a sequence such as:

```text
1. Characterize the experience
2. Place authority
3. Establish addressability
4. Place projection
5. Choose communication window
6. Add local affordances
7. Define mutation and reconciliation
8. Establish feature boundaries
9. Establish deployment boundaries
10. Strengthen quality boundaries
11. Measure and adapt
```

This sequence is provisional and must be tested against real systems.

## 7. Technology mappings

Technologies should be described as pattern configurations.

Example:

```text
Astro
  implements:
    Static Projection
    Server Projection
    Islands of Interactivity
    Deferred Client Execution
```

A framework may implement several alternative patterns depending on configuration.

## 8. Named architectures

A named architecture is treated as a reusable configuration of patterns, not as an indivisible pattern.

Examples:

- SPA
- Islands
- Server Components
- Microfrontends
- Local-first
- Document web
- Hypermedia-driven application

## 9. Evidence maturity

Every pattern should eventually carry an evidence maturity.

Suggested levels:

- `hypothesis`
- `emerging`
- `established`
- `canonical`

Maturity describes confidence in the pattern description, not desirability.

## 10. Canon evolution

Changes to the core canon should prefer:

1. extending terminology,
2. clarifying relations,
3. introducing specializations,
4. only then redefining existing concepts.

The objective is a stable conceptual core with an expanding edge.