frontend-patterns/INTENT.md

# INTENT

Status: evolving research language · Reviewed: 2026-09-28

This records the initial direction inferred from the repository scaffold. The
responsibility model, vocabulary and sequences remain hypotheses to test against
sources and contrasting applications.

## Mission

Establish **frontend-patterns** as a durable, framework-independent pattern language for frontend architecture and design.

The repository should help a human or software agent answer questions such as:

- What architectural problem am I actually trying to solve?
- Which forces are active?
- Which patterns are applicable?
- Which patterns conflict?
- Which decisions must be made before this one?
- What context will applying this pattern create?
- Which implementation approaches realize this pattern?
- What failure modes should I expect?
- Which evidence and known uses support the pattern?
- How does a named frontend architecture decompose into reusable patterns?

## Why this exists

Frontend knowledge is fragmented across:

- framework documentation,
- architecture articles,
- rendering taxonomies,
- state-management schools,
- local-first research,
- microfrontend literature,
- design-system practice,
- accessibility guidance,
- performance engineering,
- distributed-systems concepts,
- GUI architecture traditions.

These sources often discuss similar forces using incompatible vocabularies.

The project aims to reconcile them into a coherent language.

## Non-goals

The project is not primarily:

- a framework comparison site,
- a component cookbook,
- a list of React idioms,
- a collection of code snippets,
- a prescriptive "one true architecture",
- a popularity ranking of frontend technologies.

Implementation examples are useful only insofar as they illuminate patterns.

## Desired properties

The language should be:

- **Generative** — capable of helping construct architectures.
- **Relational** — patterns explicitly connect to other patterns.
- **Contextual** — every pattern exists in a context with forces.
- **Evidence-aware** — claims distinguish observation, established practice and hypothesis.
- **Multi-scale** — patterns range from application topology to interaction details.
- **Technology-independent** — named tools map into the language but do not define it.
- **Agent-readable** — structured metadata supports retrieval and reasoning.
- **Human-readable** — prose explains why and when a pattern matters.
- **Evolvable** — concepts can mature without destabilizing the whole canon.

## Success condition

The repository is successful when a practitioner or agent can start with a frontend problem description and derive a small, explainable configuration of compatible patterns, then map those patterns to implementation options.

## Initial scope and maturity

The deliverable is a versioned Markdown knowledge base: vocabulary, patterns,
relations, architecture decompositions, decision sequences, technology mappings
and traceable evidence. A running application or framework is not required.

The current corpus contains eighteen draft hypotheses, source reviews, bounded
runtime experiments and four synthetic/provisional walkthroughs. Canonical admission,
independent human validation and the M1/M2 gates remain open. Metadata and research
checks exist; full graph export and demonstrated generativity remain future work.
See the [evolution report](research/evolution/EvolutionReport.md) for the versioned
evidence profile and limitations.

## Preliminary priorities

1. Reconcile schema and template: stable identifiers, relation spelling, force
   identifiers, prerequisites, scales and evidence maturity need clear meanings.
2. Record identifiable sources with dates or versions and claim-level references;
   distinguish source claims, our interpretations and untested hypotheses.
3. Develop a small connected set of complete patterns before expanding the catalog.
   Each needs competing forces, consequences, failure modes and supporting evidence.
4. Exercise that set in contrasting server-authoritative and local-first scenarios.
   Record alternatives, decision sequences, resulting contexts and gaps.
5. Add metadata validation and graph export once the contract survives those examples.

## Evidence of useful progress

A preliminary demonstration should trace an application problem through explicit
forces to a connected pattern configuration and implementation options. Each
selected pattern should have a stable identity, justified relations, traceable
evidence and stated maturity. Explain rejected alternatives and unresolved forces.

Pattern count alone is not success. Progress should improve conceptual precision,
evidence quality or the ability to explain a concrete design decision.

## Open decisions

- Whether the nine responsibilities are sufficient and independent.
- How prerequisites differ from relations between patterns.
- How evidence maturity differs from editorial or publication status.
- How to represent patterns spanning multiple scales.
- Which metadata and evaluation cases enable reliable agent retrieval.

`research/plan/ResearchProgram.md` provides a provisional roadmap; its milestones
describe planned work, not completed capabilities.

## Continuous learning

The language is intended to evolve indefinitely. Complete bounded investigations and
review milestones; do not treat the language as finished. Maturity is a reversible
evidence judgment, including for canonical records. Preserve superseded claims and
explain what new evidence changed, what remains uncertain and what the investigation
cost when measured.

Track applicability, trustworthiness, usefulness, coherence, maintainability and
learning efficiency separately. Never infer health from catalog size or combine these
into a maturity percentage. Rapid initial learning and eventual diminishing returns
are hypotheses to assess within comparable streams and effort-accounted cycles.
Independent confirmation remains valuable even when it does not change wording.
The [evolution method](research/evolution/README.md) defines the baseline, ledger,
reporting and prospective measurement protocol.