Semantic table design

Source and version

Repository path

.agents/skills/semantic-table-design/SKILL.md

Source revision

cfaa53f5b7500e3901d8470e1e471cd0230ff2a5

Source SHA-256

f8e2d4232577ec7b6f7eab91ca0f39c3431001cb1145af6c9f73b1bd1eb67bd4

Publication standing

Public ready

Included source files

• .agents/skills/semantic-table-design/references/table-design-contract.v0.1.md
  SHA-256 b411b1142813959af4831a2b7b9d85edbf8505e54b6f8b6c9ed148e3759ec37e
• .agents/skills/semantic-table-design/references/supplemental-table-labels.md
  SHA-256 be199d22d30bd4568c2e1a05ab19d1060f5c0d717cee1c57da793ec97b6241a2

Complete skill source

The Markdown below matches the exact source text. The format link above opens the file on its own.

---
name: semantic-table-design
description: Designs readable native-semantic tables and context-complete extracted records. Applies when a new or revised table's header relationships, row completeness, supplemental wording, comparison geometry, or partial-row ingestion affects a visitor or receiving-tool task.
---

# Semantic table design

## Contract

- **What:** A source-owned table contract that preserves the reader's operation, native header relationships, precise values and locally complete meaning across visual, interactive and extracted forms.
- **When:** A new table or a change to header relationships, record completeness, comparison geometry or supplemental context affects a named reader or receiving-tool task. A small correction with established meaning and ownership can use direct reasoning.
- **Boundaries:** Authored semantics and the owning generator establish meaning; native HTML carries baseline relationships and custom attributes serve named receivers. Literal names, language, units and technical notation retain their identity. Geometry, extraction and source parity establish separate claims. Accessibility conformance, arbitrary model or ATS ingestion, parser adoption and publication retain their own evidence and authority.
- **Result:** One bounded table-family disposition naming the reader operation, semantic and source owners, header relationships, field roles, supplemental context, scroll boundary, affected states, fitting observations and any unresolved interpretation.

## Fit and attention

- **Useful when:** A reader must look up, compare, enter or reconcile precise values, or a receiving tool encounters records apart from their page.
- **Poor fit when:** Content is primarily sequential prose, a chart alone serves the requested pattern-reading task, or a read-only inventory needs no design change.
- **Smallest useful dose:** One affected table or shared family, its reader operation and meaning owner, and the observation that can change the current decision.
- **Foregrounds:** Relationships between headers and values, intact qualifications, complete record context and the actual width available to the reader.
- **May under-attend:** Correct source associations can coexist with difficult interaction, and good geometry can coexist with incorrect meaning. Each consequential receiving behavior needs its own observation.
- **Material result:** A usable comparison or record, or an explicit source-owner question that prevents an ambiguous transformation from being published.
- **Interactions:** This skill owns the table's semantic and comparison disposition. Source-authority mapping can resolve a disputed generator; embedded-prototype layout owns measured parent/child pressure; cost analysis owns traversal and expansion; visual verification selects fitting rendered evidence. Each peer releases its contribution to the one table disposition rather than producing a competing completion claim.
- **Rest or release when:** The changed boundary has adequate evidence and an accountable receiver, or a specific uncertainty has a recovery route. A new state or owner can reopen the fitting scope.

## Inputs, defaults and output

- **Minimum inputs:** The affected table or canonical renderer, a reader operation, the relevant state, and the authority granted for inspection or change. A supplemental-label task also names the consumer and the transferred unit: table, row or cell.
- **Optional context:** Existing relationship fixtures, column definitions, source/projection declarations, viewport or print constraints, and earlier evidence with its actual scope.
- **Defaults:** Begin with one table or shared family and the existing native structure and styles. When a consumer is unspecified, preserve literal values and record the missing receiving contract before changing metadata. When runtime or private access is unavailable, return the source-supported decision and the exact observation still needed.
- **Output:** One receiving artifact: a source-owned repair with fitting evidence, an acceptance map, or a bounded question. It carries the changed relationship, literal-value protections, covered states and next receiver when needed. A separate ledger is useful only when it changes a later decision.

## Rules

### Rule: Row changes retain family admission

Table admission also covers adding, removing, or renaming rows within an
existing table, including catalog rows. Reuse the declared projector and
preserve inventory ownership. Reconcile affected labels, row identities,
per-page counts, and aggregate totals against the combined receiving source,
while retaining independently specified native-header and meaningful-row
expectations. When another PR owns an affected inventory or assertion,
identify that owner and include reconciliation in the integration handoff.

### Rule: The reader operation selects the representation

Lookup, cross-row comparison, entry, reconciliation and evidence inspection have
different reading needs. A table serves two-dimensional relationships or precise
values; a chart may accompany it for patterns. Ordering, grouping and selective
emphasis support the named operation within the existing visual language. A
conversion to cards preserves a comparison route when comparison remains a task.

### Rule: Semantic ownership includes creation and change

The collaborator traces authored markup, shared semantic descriptors, generators,
runtime data, styles, maintained projections and applicable export/print output.
A generated copy returns to its canonical owner. An authored patch preserves its
unowned source. Historical copies retain their comparison role. One reviewed
wording decision can serve several renderers without giving a display normalizer
authority over every string they receive.

A new table or visitor page enters the existing family's observation contract.
Before authoring, identify its semantic owner, source inventory, label projector
or renderer, and acceptance expectations. Register the new carrier where that
existing contract requires membership, and use its declared table, header, row
and cell context rules. Plausible hand-authored labels establish neither inventory
coverage nor agreement with the owning projection. When the receiving system has
no inventory or projector, define the bounded artifact contract directly; creating
a new registry or harness needs its own demonstrated use.

### Rule: Header topology is explicit

Each data field has an understood relationship to its column, row and applicable
group headers. Native `th`, fitting `scope` and, where needed, explicit header
associations carry those relationships. Identity follows the semantic contract,
which may use an offset header or several fields. Complex spans and repeated
headings receive a relationship map or a simpler design before a flat extractor
assumes one positional label per cell.

### Rule: Record shape remains meaningful

A declared simple table validates every record's required fields, including a row
left with headers only after a data cell disappears. A present blank value differs
from a structurally absent field. Group headings, totals and empty-state rows
retain their declared roles. Ambiguous structure returns to its source owner
before derived labels can make a partial record appear complete.

### Rule: Supplemental records carry the context their receiver needs

A detached record retains topic, record identity, field meaning, value and
applicable units, status, period, conditions and evidence qualifications. Source
or stable identifiers travel when the receiver uses them. Custom `data-label`
values supplement this contract; native relationships and visible meaning remain
usable when those attributes are ignored. Added repetition earns its place by
restoring context that extraction would otherwise lose.

### Rule: Plain-word labels preserve meaning and literal data

Supplemental wording derives from the same semantic owner as the visible label.
A known decorative separator or directional shorthand can receive ordinary words
or simple punctuation when its interpretation is clear. Accented names, symbols
with technical meaning, units, identifiers and user-entered records retain their
literal content. Normalization acts on owned semantic components before the
existing context-appropriate escaper; a general Unicode deletion or transliteration
rule has a different, ungranted scope.

### Rule: Values keep their distinctions

Zero, blank, unavailable, invalid, inapplicable and uncertainty retain the source
contract's distinct meanings. Signs, precision, units, denominators and periods
stay interpretable. Qualifiers remain adjacent in the visible record and available
to its named extractor. Identity, numeric, status, prose and code/identifier
columns receive fitting reading and wrapping choices.

### Rule: Comparison geometry belongs to its actual container

Necessary two-dimensional width can live inside a named, keyboard-reachable local
scroll region while surrounding prose and controls reflow. Column measures protect
individual values and text, including the final column. Embedded work uses the
child's measured available width as well as standalone controls; a nominal outer
viewport alone leaves the child constraint unspecified.

### Rule: Derived work is bounded before expansion

Transformation admission accounts for source size, structure, repeated labels,
escaping and total output before materializing large derived collections.
Repeated caption copies and scanner suffix copies have their own cost. Raw code
and unselected owners retain their boundaries. Unsupported syntax, source drift
and missing semantic fields receive explicit outcomes rather than partial
publication of a supposedly complete table.

### Rule: Observation follows the changed boundary

The smallest sufficient evidence distinguishes meaning, shape, native structure,
source preservation, generated/extracted parity, rendered geometry and interaction.
A metadata-only wording change begins with its label consumers and source or
generator contracts. A layout, state or accessible-relationship change selects
the relevant rendered and interaction cases. Existing coverage remains reusable
only within its actual identity and scope; a browser pass is neither a universal
requirement for every edit nor a substitute for semantic evidence.

## Operating sequence

1. **Select the receiving operation:** Identify lookup, comparison, entry, reconciliation or detached-record use. Choose direct reasoning when the requested correction already has a clear owner and meaning.
2. **Trace the source boundary:** Locate authored markup or the canonical renderer, runtime record, styles, maintained copies, and relevant report or print outputs. For a new page or table, discover and satisfy the existing family's source-registration, projection and coverage contract before treating the artifact as admitted. Identify the exact component the task authorizes creating or changing.
3. **Map meaning before projection:** Trace representative cells to their row, column and group headers. Separate complete records, present blanks, absent fields, summaries and empty states. Preserve literal identifiers, names and units.
4. **Choose the smallest repair:** Reuse existing table and scroll patterns. Add supplemental context only for its named consumer. Return unsupported topology or ambiguous wording to the semantic owner before transformation.
5. **Observe the changed claim:** Select source, extraction, state, geometry or interaction evidence from the changed-boundary matrix. A matching pair of empty outputs needs an independent meaningful-record expectation. Preserve previous observations with their source and coverage limits.
6. **Hand back and release:** State the table disposition, what the evidence establishes, the adjacent unknown and its receiver. Further populations or a wider browser campaign enter through a new consequential uncertainty.

## Decisive scenarios

### Scenario: A row leaves its page

- **Given:** A row contains a numeric value whose unit and period are stated only above the table.
- **When:** A named receiver exports that row independently.
- **Then:** The exported record carries the applicable topic, identity, field, unit, period and qualification, and its test checks the detached meaning.

### Scenario: A flat label rule meets grouped headers

- **Given:** Two column groups each contain a field named `Actual`.
- **When:** A simple projector cannot retain their group distinctions.
- **Then:** The source owner supplies an explicit association/record contract or simplifies the table; the unresolved projection remains a visible review disposition.

### Scenario: An isolated copy correction is already understood

- **Given:** One caption contains a spelling error, its owner is known, and its wording is outside generated-label and interaction contracts.
- **When:** The task asks for that correction.
- **Then:** Direct reasoning repairs the caption within the granted scope; the table-family audit and browser campaign remain released.

## Strain and recovery

Repeated global punctuation rules, guessed header mappings, a growing family list,
or repeated campaigns without a new acceptance question indicate scope strain.
Back off to one source-owned record and the relationship that changes the decision.
Preserve authored bytes, accepted state, completed observations and ambiguous
material. A smaller admitted grammar or an explicit owner question can complete
the present return. Re-entry requires the missing association, a changed consumer,
or a reproduced interaction or layout condition, rather than more processing alone.

## Evidence, publication and authority

These rules carry repository-local material-use observations from table-label,
comparison, print and embedded-layout repairs, informed by the standards and
practitioner references below. Their transferable contribution is the distinction
among semantic, literal, rendered and receiving contracts. Fresh-context exercises
can probe that distinction; they establish the exercised decisions rather than
cross-platform effectiveness or arbitrary AI ingestion.

Publication readiness describes a coherent, audience-safe source package. Contract
revision and evidence maturity stay revisable; current task authority governs every
edit, test and release. The complete method and both references work without private
workspace access. Optional repository implementation links support deeper inspection;
their availability leaves the portable method intact.

## Conditional context

- Load [Table design contract v0.1](references/table-design-contract.v0.1.md) when reader jobs, header topology, incomplete records, column geometry, embedded width or state changes need an implementation and observation matrix.
- Load [Supplemental table labels](references/supplemental-table-labels.md) when authored or generated labels need contextual rewording, escaping, receiver-complete context, source/generator parity or bounded expansion.

The references distinguish HTML requirements, accessibility guidance and local
design choices. Their scenarios specify intended decisions; execution records
remain with the receiving task.

## Completion and re-entry

The receiver can identify the owner, understand the comparison or detached
record, operate the affected controls, and locate evidence for the changed
boundary. Any unsupported shape or unobserved behavior has a named receiver and
re-entry condition. A new consumer, vocabulary ambiguity, projection drift,
changed parent width or missing field reopens the smallest fitting scope.