A grammar for the work.

Martlet: a grammar of related things

Experimental grammar 0.3 · Core 2.2.0 candidate · Astro 1.2.0 candidate · React 0.1.0

Martlet makes substantial work approachable through proportion, proximity, readable sequence, and continuity. Its warmth must survive a compact collection, an error, or a page without its mark. The adopted charter supplies the criteria; these rules turn them into an application vocabulary to exercise and revise.

Source authority and current decisions

Existing origin objects are the baseline. Read the decisions MCP reference or the source-decision profile before choosing visual rules. Distinguish observed source roles, a contextual translation, and a new application extension. Do not add a global gold stripe, decorative monospace labels, arbitrary accent rules, or mechanically opposite family layouts. Keep new capabilities only with a stated task purpose. The October 23 audit is a fixed record; the reconciliation ledger records implemented decisions and remaining gaps. This remains an experimental grammar, not a declaration of stability.

Begin with relationships

Decide what belongs together before drawing containers. A label, control, and useful explanation form a field. Related fields form a group. Groups participating in one decision form a task region. Use progressively stronger separation to express those changes of relationship. Do not give every paragraph or field its own card.

The optional source profile exposes --martlet-field-gap at 0.5rem, --martlet-group-gap at 1.5rem, and --martlet-region-gap at 2.5rem. They map to existing foundation scale steps 2, 4, and 5. These are experimental application defaults, not a requirement to space every adjacent element equally. Use the field role inside a relationship, the group role between related units, and the region role between different purposes. A compact composition may reduce local padding while retaining the relationship hierarchy.

Give the work a readable sequence

Establish orientation, the subject, supporting context, and the next useful action. Use a bounded reading measure for sustained text. Interface labels and metadata use Lato; Cambo supports prose and expressive headings; Cinzel remains selective rather than spreading to every control. In light mode use the observed source ink, navy heading and cream support roles; keep the actual rendered source link color. Existing dark semantic tokens supply an explicit extension with the same source anatomy. Retain original marks when identifying the system; adopting applications provide their own identity.

Reading hierarchy also applies to forms, tables, and working panels. A toolbar can be compact and a table can contain many rows. Neither requires display-size headings or article-sized spacing inside every control. Preserve an understandable sequence and proximity within each local group.

Place assistance at the decision

Keep a field’s requirement and useful hint beside it. Use explicit action labels that describe the outcome. Place an object’s actions with the object, and collection actions with the collection. Do not use a row’s whole surface as an ambiguous combination of selection, opening, and editing. Decide and communicate what activation does.

Reveal secondary options when relevant without hiding prerequisites. Put essential consequences in view before commitment. Warm language must still distinguish cancel, reset, discard, remove, and delete precisely.

Preserve continuity

Use expansion and loading to explain the change, preserving useful content and the person’s place. Do not erase an editor when a save fails. Announce meaningful completion and provide an immediate recovery path. On a failed form submission, show actionable errors, retain input, and move focus to a useful summary when errors are distributed.

Unsaved navigation requires a clear choice that keeps the draft available. Cancelling that choice returns to editing. A reversible removal can use an explicit undo path instead of interrupting every action with a modal. An irreversible action requires proportionate consequence guidance. Motion is optional explanation; the result must remain clear with reduced motion.

Choose the frame from the task

Top navigation, side navigation, and focused work without primary navigation are all native possibilities. Use a rail when persistent destinations are valuable. Use a top bar when compact orientation leaves the work more room. Use a focused frame when the task benefits from sustained attention. None defines Martlet by itself.

Change the composition when available space no longer supports its relationships. Use the left source document index, with unnumbered parent/child hierarchy and separate supporting material. The inline article TOC is a different named variant. Reflow the index into a cream in-flow block when the available width is insufficient, without losing hierarchy or navigation. Preserve source order, keyboard access, readable controls, and return paths. Long labels and enlarged text are design inputs, not exceptional content to clip away.

Choose a grouping, then a density

Give one decision a readable progression: purpose, related inputs, nearby assistance and the committing action. A border marks a change in purpose only when proximity and headings are insufficient. Related short fields may share a row; unrelated decisions do not become a grid merely because space is available.

Use comfortable density for the current reference patterns. A compact mode remains proposed, with no new public density prop. Adjust related padding locally only while preserving readable text, usable targets, visible labels and the field/group/region hierarchy. Source page section spacing does not belong inside an editor. A source index or footer is an object-specific composition; it does not establish a universal application rail or surface.

Bind actions to committed scope

Put a field’s assistance beside that field, object commands beside the object, and collection commands beside a named collection. A pending query and its previous results are different scopes: identify both. Retain input and useful results after failure, with a recovery action that names the failed operation. Selection belongs to stable record identities in a declared result scope; clearing, retaining or extending it must follow a documented transition, not an accidental rerender.

The validated-form and query-results contracts add concrete state transitions, focus destinations and narrow-layout rules. They are application extensions. Shared native keyboard conventions do not make the languages interchangeable, and a shared grammar rule does not imply the same framework API. The coverage ledger distinguishes documented rules, checked reference behavior and open consumer evidence.

Use layers for their actual purpose

An inline disclosure stays in document flow. A non-modal popup anchors to its trigger and retains the source navigation surface. A modal interrupts the task, names its consequence and uses the native dialog top layer with a clear dismissal route. A backdrop belongs to the modal; it is not required for every overlay. Keep focus visible and return it to a meaningful trigger when a temporary surface closes. Motion never carries the only explanation of a state change.

Working pattern: collection, reading, and editing

The Commonplace specimen lets a person browse related notes, narrow the collection, open one for sustained reading, and edit it. Its folder shelf and collection-level search provide orientation. The collection uses generous separation between ideas, with each note’s heading, excerpt, and explicit reading action forming one group. Opening a note changes to a bounded reading context; a named back action returns to the same folder and query. Edit enters an explicit form; the reading context is restored after saving or cancelling.

This is one Martlet pattern, not a universal application template. A comparison-heavy task can use a persistent split view. Select it when the work requires simultaneous reference, then apply the same grouping, hierarchy, and continuity rules.

Pattern rules and state coverage

Search stays scoped to the named folder. A no-match state explains how to recover and offers Clear search. Empty content explains what belongs there and offers creation. Choosing a different folder is a context change, distinct from changing the query. Successful saving commits the draft and announces success; failed saving retains the fields and offers retry. Leaving a changed editor asks whether to continue editing or discard. Moving a saved note to trash offers undo.

The specimen uses fictional, session-only data. Reloading restores its initial notes. The failure inspection control deliberately fails the next save; it is documentation tooling, not a production product feature. Network retrieval, durable persistence, collaboration, and rich text are outside this specimen’s implementation.

Review the grammar

Inspect relationships before decoration: can someone tell which help belongs to which control, which action affects which object, and where one task becomes another? Does the same reasoning work in a compact panel and a long form? Can they recover their place after a change? Remove the mark and reduce color distinctions; hierarchy, proportion, grouping, and interaction continuity must still carry the language.

Keyboard conventions, focus visibility, labels, and usable recovery are shared obligations with other sound systems. Do not invent unusual behavior merely to look independent. Manual assistive-technology review, localization, RTL adaptation, and sustained use remain required before stability.

Martlet grammar coverage review

Review 0.3 · October 24, 2026 · Experimental

The baseline grammar described intent and an experimental collection/editor. This review adds decision rules for grouping, density, action scope, layers, validated forms and queried results. Existing origin objects remain authoritative. New application patterns are justified extensions and are not retrospectively attributed to the origin site.

Acceptance and limits

Each pattern contract names its purpose, anatomy, scope, states, keyboard/focus behavior, responsive behavior and implementation availability. Automated results are recorded separately from documented requirements. A rule is not stable merely because a specimen passes. New form and results specimens use deterministic session state and simulated latency/failure. They do not add a new application or change the collection/editor into a production service.

The foundations no longer claim that every React target is 44 pixels, no longer require a backdrop for all overlays, and now acknowledge the optional core source-profile aliases. Modal focus behavior, native read-only/disabled distinctions, selection scope and draft-versus-applied query are explicit. Compatibility remains additive; existing package defaults and APIs are retained.

Framework boundaries

Core owns grammar, semantic roles and source profiles. React supplies interactive specimens using existing exports. Astro retains its documented component inventory and can use the same native HTML semantics; host scripts own form/query controllers. The main reference and agent snapshots identify this exact canonical revision. No framework receives an implementation claim from shared prose alone.

Reference method

The source audit, adopted charter and actual exported APIs govern these decisions. Carbon’s form, loading and filtering guidance informed the breadth of questions, not either language’s palette or composition. Our search controls retain visible labels under our own grammar. Target sizing follows the distinctions in W3C SC 2.5.8, without treating automated checks as overall WCAG certification.

Martlet: a validated form

Experimental pattern contract 0.3 · Application extension · React reference specimen

Purpose and composition

Use this pattern for a deliberate submission with multiple related fields and recoverable errors. The specimen is a publication request with title, summary, request type, response name/address and a notification preference. It is a controlled documentation example; it sends nothing and stores nothing beyond the mounted specimen.

Start with the request and its purpose, then related details, then response preferences, and finally the committing action. Keep one readable progression. Related short fields may share a row when their labels and hints fit; the row returns to one column when it no longer does. Supporting explanation stays next to the decision it informs. A separate guidance region follows the form in source order.

Use the field relationship for label, control, hint and error; group spacing for sibling fields; and region spacing between different decisions. A native fieldset and legend identify a real group. Do not add a card per field. Keep the primary submit action after the editable groups. Secondary discard/reset actions describe their consequence and remain visually subordinate. The specimen uses comfortable density; it introduces no compact-density API.

Validation and state transitions

The pending operation is short and simulated. Unmounting invalidates its completion; a late timer cannot update another specimen. Reset is unavailable while saving. The draft guard covers the specimen’s Reset action; documentation navigation is outside that guard and unmounts the example. This is an explicit hosting boundary, not a claim of full application navigation protection.

Semantics and responsive behavior

Use native form, label, input, select, textarea, checkbox, fieldset and button semantics. Required indicators appear in labels and requirements in hints. Read-only text remains inspectable and available to native form behavior; disabled controls are temporarily unavailable. Do not invent readOnly support for a native select or checkbox. Name the form, error summary and dialog, and expose meaningful pending/saved state without repeated announcements.

At narrow widths the groups and actions stack in source order. Long text and enlarged text wrap without clipping. The guidance region follows the fields; no visual reordering changes keyboard order. Reduced motion does not remove state text. For print, retain the current values and context; hide only documentation inspection controls.

Implementation and evidence boundaries

React composes Field, TextInput, Textarea, Select, Checkbox, Fieldset, Button, ErrorSummary and Dialog. These are existing exports; no new form-controller API is implied. Core supplies typography and spacing roles. Astro can express the same native HTML structure, but validation, transport, draft management and focus transitions remain host code; there is no Astro Form controller in this candidate.

The reference includes validation, pending, failed/retry, saved and discard-dialog examples. Browser assertions cover values, linked errors, focus restoration, reflow and automated accessibility. Real server errors, conflict resolution, authentication, uploads and manual assistive-technology review remain outside this specimen. New controls and full dark mode remain experimental.

Martlet: query, results and selection

Experimental pattern contract 0.3 · Application extension · React reference specimen

Purpose and composition

Use a results table when the task benefits from comparing several attributes across records. The reference uses the existing component catalogue as its dataset. Search, group filter, sorting, paging and selection are host logic composed from existing primitives. The preparation dialog makes no remote request or actual review decision.

Put scope and search before a readable table. The table is a deliberate comparison surface, not the default container for every collection. Keep each component name with its purpose and group; selected-item commands follow the named results region. A reading task may instead use the existing collection/read pattern. Choose by what the person must compare.

Visible search and filter labels name their scope. Enter or Apply query submits the draft query. Changing an unapplied input does not relabel old results. Show the committed query, result count and page independently of what is being typed. Put a table caption on the table and a keyboard-accessible name on its scrolling region. Do not make every row simultaneously mean selection, navigation and editing.

Query and result contract

The reference simulates asynchronous completion and an optional one-shot failure. Each request carries a generation: an obsolete completion cannot replace newer state or update an unmounted specimen. The available sample data and sorting are deterministic. No remote retrieval, server pagination or durable selection is claimed.

Selection and dialog contract

Selection means the checked records on the currently committed result page. Native checkboxes name each record. There is no select-all control, cross-page selection, mixed checkbox state or implied edit permission in this contract. The count is textual; row color is supplementary. Query/filter/sort/page changes clear selection only when their new result set commits. A failed request retains previous selection and scope for recovery.

Review selection opens a native modal listing the exact selected component names. Prepare comparison is a simulated operation. Failure keeps the dialog and selection available for retry. Success closes the dialog, retains selection and announces completion. Cancel or Escape cancels an in-flight preparation, preserves selection and returns focus to Review selection. A late completion cannot announce success after dismissal. No action in this specimen promotes component maturity or records a real readiness review.

Native dialog semantics make the background inert and keep modal keyboard behavior conventional. Non-modal navigation popups and disclosures do not inherit that modal contract or require a backdrop.

Responsive behavior and implementation

Query controls wrap into one coherent sequence; status and commands wrap without clipping. A genuinely comparative table may scroll within its labelled region at narrow widths. Keep its caption, row-selection labels and all columns. Do not hide data or turn each row into a different task simply to remove horizontal scrolling. Surrounding prose and controls must still reflow.

React uses Field, TextInput, Select, Checkbox, DataTable, Pagination, Button and Dialog. A host owns querying, sorting, paging, selection and request cancellation. Core owns the existing family styles. Astro native HTML guidance shares these semantics, but an interactive results controller is not supplied by the Astro package. Both languages permit a table or a list when the task supports it; neither is compulsory for one family.

Tests exercise changed/unapplied scope, pending and failed retrieval, retry, no matches, paging, selection reset, modal failure/cancel/success, focus restoration, long text, narrow reflow and automated accessibility. Manual screen-reader review, localization/RTL, large datasets and real network races remain open consumer work.

Martlet source decisions

Origin reconciliation 0.2 · Consolidation candidate · Original palette and existing defaults retained

Use jameshoward.us as the authority for existing objects. This profile distinguishes restored source roles from application extensions. The full grammar remains experimental. Original source commit: 32b7166a629ea696147d0d779d911b713e4baf7e, repository k3jph/k3jph.github.io. Review src/styles/global.css, content.css, document-pages.css, and src/components/{SiteHeader,SiteFooter,PageIndex,TableOfContents,PageIntro}.astro at that commit. The audit and reconciliation ledger record evidence and remaining limits.

Existing source objects

Explicit application extensions

AppShell is a compact application frame, not the origin website’s scrolling masthead. Top/side/none remain available. Its existing default remains top for compatibility; it carries no automatic gold stripe and no built-in prose. Navigation content and identity belong to the caller.

Field, hint and error linkage, native selection controls, a task dialog, error summary, status notice, badge, switch, manual tabs, controlled data paging, and note workflows are application extensions. Their purpose is visible labels, understandable scope/state, retained work and recovery. Keep native keyboard conventions and distinguish disabled, read-only, invalid, pending and saved. Invalid styling matches aria-invalid="true" only. ErrorSummary uses a consistent leading severity rule; no forced opposite Krigsvold treatment. Tabs have a selected underline without decorative rounded/fill variants. DefinitionList supports layout="rows", "stack" or "grid" in either family.

The field/group/region application roles are .5/1.5/2.5rem. They use source scale values but their relationship assignments remain experimental. They do not replace source section spacing or reading rhythm. Notebook rows have no meaningless ordinals. Its find/read/edit progression is a task choice available to other frames too.

Dark mode preserves source anatomy using existing theme semantic contrast roles. It is an extension, not evidence that every origin object has a dark counterpart. Code surfaces retain theme code roles pending source-matched code specimen review. The source index, its hierarchy and quote accents remain identifiable; do not turn dark mode into permission for decorative rules.

Boundary and evidence

The theme-site bird is an existing system mark used by documentation; adopting apps supply their own brand. The documentation component finder, preview frames, copy controls, failure simulator and local-only saves are host tools. Source imagery, seasonal treatments, personal identity, analytics and legal policy do not become global language requirements.

Full media/figure/footnote/maths, source card/archive variants and complete application pattern breadth are not shipped contracts merely because their CSS exists at the origin. Accessibility, localization/RTL, forced colors across complete pages and sustained use still require evidence. Retrieve this decision profile alongside grammar and API references; a source hash identifies content, not design correctness.

Framework consolidation

Core 2.2.0 and Astro 1.2.0 are unreleased candidates. The source profile is an opt-in import and class; existing core defaults and existing Astro slots remain compatible. New TableOfContents and grouped SiteFooter anatomy are available in the paired candidate packages. React 0.1.0 retains its existing theme 2.1.0 dependency and React-specific events and focus contracts. Framework support is recorded in language.json. These additions do not make the grammar stable.

Grammar review 0.3

Validated forms and queried results add explicit application contracts for grouping, action scope, committed versus draft queries, current-page selection and modal recovery. These are experimental extensions, with separate family composition choices and shared native behavior. No original palette, mark, header direction or existing component default changes. Read docs/coverage.md and docs/patterns/ for the bounded evidence and remaining vocabulary.

Framework scope

The source website header observations describe the origin object and its reference-host translation. Astro SiteHeader retains a generic wrapping-link header; it does not claim the source masthead, responsive menu controller or React print behavior. Inspect the target platform API and complete composition rather than transferring another renderer’s props or defaults.