APGC v0.1 — Artifact Panel Geometry Contract

Status: Draft v0.1 Host System: Aptlantis Studio Compatible With: SESM v0.3.x, NIPC v0.1.x, AIC v0.1.x, Neon Ink v0.1.x Scope: Manga-informed quadrilateral panel grammar, angle behavior, shape families, safe zones, responsive fallbacks, SVG/HTML geometry rules, and validation guidance for Aptlantis Studio artifacts.

Source: Docs/APGC-v0.1.md (only version in the source tree).

1. Overview

The Artifact Panel Geometry Contract defines the geometry language for Aptlantis Studio interface artifacts.

Aptlantis Studio uses SVGs and HTML panels as durable visual artifacts. SESM, NIPC, and AIC already define meaning, color, metadata, fields, and layout regions. APGC defines the missing layer:

What shape should the artifact have?
How angular may it be?
How manga-like may the composition become?
Which corners may move?
Where is text safe?
How do panels interlock?
How does geometry support reading order?

APGC exists because Aptlantis Studio panels are not limited to squares and rectangles. Many panels may be four-sided shapes with slanted edges, asymmetric corners, trapezoid-like forms, manga-inspired compositions, cut-corner containers, and shard accents.

The purpose of APGC is to make those shapes deterministic rather than random.

Core rule:

Shape communicates visual rhythm, energy, and composition. Color communicates semantic role. State controls intensity. Metadata carries meaning.

2. Relationship To Existing Specs

Layer	Spec	Responsibility
Meaning	SESM	Embedded metadata, asset identity, provenance, links, crawler/LLM hints
Palette	NIPC	Semantic color families, psychological intent, hue rules, intensity validation
Artifact Contract	AIC	Artifact types, required fields, layout regions, render targets, state mapping
Expression	Neon Ink	Brand system, typography, panel grammar, page composition, voice
Geometry	This document (APGC)	Shape families, corner behavior, angle energy, safe zones, panel rhythm

APGC does not replace any existing layer. It gives generators and design agents a formal way to decide geometry.

3. Goals

Prevent geometry drift across generated SVG and HTML artifacts.
Make manga-inspired panel design deterministic and reusable.
Support non-rectangular four-sided panels without sacrificing readability.
Define shape families that communicate visual energy and composition.
Preserve safe text regions inside angled or asymmetric panels.
Support SVG-first artifact generation.
Provide CSS clip-path equivalents for HTML surfaces.
Give design agents and build agents explicit geometry rules.
Allow expressive layouts while preserving archive-grade structure.
Keep Neon Ink visually distinctive without becoming chaotic.

4. Non-Goals

APGC does not define color semantics, replace NIPC intensity rules, define dataset schemas, replace AIC artifact contracts, replace SESM metadata, require every artifact to be non-rectangular, require manga-style geometry everywhere, require JavaScript or animation, define full page routing/content strategy, or make geometry the only carrier of meaning.

Geometry is an expressive layer, not the source of truth.

5. Design Philosophy

5.1 Rectangles Are Still Valid

Rectangles are useful for dense data, long text, tables, metadata, stable documentation, archive views, and low-energy utility panels. The goal is not to eliminate rectangles — it is to make geometry a deliberate tool.

5.2 Manga Energy Without Manga Confusion

Aptlantis Studio should borrow the useful part of manga composition — motion, energy, hierarchy, section rhythm, dramatic framing, diagonal reading flow, expressive information architecture — while avoiding unreadable text regions, random angles, excessive fragmentation, unclear reading order, and too many competing focal points.

5.3 Shape Is Rhythm, Not Truth

A panel shape may suggest energy, motion, priority, or editorial framing, but it must not be the only way a user learns critical meaning. Error must still be represented by semantic state and text; verified status must still be represented by state and metadata; archive status must still be visible or embedded.

5.4 Geometry Should Reduce Drift

A generator should not improvise a slightly random polygon, random corner cuts, random diagonal panel, or random cyberpunk shape. It should select from APGC-defined shape families, angle profiles, safe zones, and validation rules.

6. Terminology

Panel: A visual container that holds an artifact, section, metric, Q&A item, dataset summary, pipeline state, or brand surface.
Artifact Panel: A panel governed by AIC and APGC.
Shape Family: A named geometry category such as rect-stable, cut-corner, slant-forward, or manga-panel-a.
Shape Role: The purpose geometry plays in the composition, e.g. stable-container, section-rhythm, forward-motion, archive-history, spotlight-frame.
Angle Energy: A numeric measure of how visually dynamic or angular a panel is.
Corner Profile: How corners behave (square, soft-radius, single-cut, dual-cut, asymmetric-soft, asymmetric-sharp).
Outer Polygon: The visible polygon or path that defines the panel boundary.
Inner Safe Zone: The area inside the panel where text and important UI elements may safely render.
Bleed Zone: The outer region where decorative strokes, glows, shadows, image crops, and accents may extend.
Gutter: The space between adjacent panels in a mosaic or page section.
Shard: A small angular accent shape used as a badge, marker, corner fragment, or visual pointer.
Manga Mosaic: A group of panels arranged with controlled asymmetry, varied shapes, and directional rhythm inspired by comic/manga page layouts.

7. Core Geometry Model

APGC separates geometry into five decisions: shape family, shape role, angle energy, corner profile, safe zone.

{
  "geometry": {
    "contract": "apgc-0.1",
    "shape_family": "manga-panel-a",
    "shape_role": "section-rhythm",
    "angle_energy": 2,
    "skew_direction": "forward",
    "corner_profile": "asymmetric-soft",
    "safe_zone": { "type": "inset-rect", "x": 32, "y": 28, "width": 536, "height": 164 },
    "responsive_fallback": "soft-card"
  }
}

8. Shape Families

{
  "shape_families": ["rect-stable", "soft-card", "cut-corner", "slant-forward", "slant-back", "trapezoid-wide", "trapezoid-tall", "manga-panel-a", "manga-panel-b", "manga-panel-c", "shard", "burst"]
}

Shape Family	Energy Range	Meaning	Best Use
`rect-stable`	0	Stability, neutrality, dense readability	Docs, tables, metadata, long text
`soft-card`	0–1	Friendly artifact card	Dataset cards, Q&A items, ordinary panels
`cut-corner`	1–2	Technical, compiled, artifact-like	Schema cards, download cards, generated artifacts
`slant-forward`	1–3	Motion, progress, next step	Pipelines, navigation, process flow
`slant-back`	1–3	History, archive, reflection	Changelog, snapshots, prior versions
`trapezoid-wide`	1–3	Section identity, banner energy	Headers, hero strips, category panels
`trapezoid-tall`	1–3	Vertical rail, sidebar energy	Sidebars, section rails, tall graphics
`manga-panel-a`	2–3	Dynamic but readable	Featured sections, section mosaics
`manga-panel-b`	3–4	Strong asymmetry	Hero mosaics, visual-first panels
`manga-panel-c`	4	Dramatic composition	Rare campaign or splash surfaces
`shard`	1–4	Small angular accent	Badges, labels, pointer marks
`burst`	4–5	Interrupt, spotlight, dramatic emphasis	Rare hero/alert graphics only

9. Angle Energy Scale

Energy	Name	Description	Allowed Use
0	Rectangular	Stable, grid-aligned, quiet	Dense content, docs, metadata
1	Technical Cut	Slightly shaped, artifact-like	Cards, schema panels, downloads
2	Editorial Slant	Manga/comic rhythm, still readable	Q&A, feature cards, process panels
3	Dynamic Panel	Strong motion and asymmetry	Visual sections, hero support panels
4	Dramatic Panel	High-energy composition	Hero mosaics, marketing surfaces
5	Rupture	Visual interrupt	Rare alerts, splash graphics, never dense text

Dense text:        0–2
Stats tiles:       0–2
Dataset cards:     0–2
Pipeline panels:   1–3
Q&A items:         0–2
Hero mosaics:      2–4
Marketing art:     3–5
Error panels:      1–2
Archive panels:    0–2

No artifact with long body text should exceed angle_energy: 2 unless the text is contained inside a verified inner safe zone.

10. Directional Semantics

Geometry may imply direction, but it must remain secondary to explicit labels, color, state, and metadata.

{ "skew_direction": ["none", "forward", "back", "upward", "downward", "inward", "outward", "mixed"] }

Direction	Meaning	Use
`none`	Stable, neutral	Docs, metadata, calm cards
`forward`	Continue, progress, next step	Pipelines, navigation, actions
`back`	History, prior state, archive	Snapshots, changelog, older releases
`upward`	Growth, elevation, spotlight	Featured metrics, improvement
`downward`	Drill-down, detail, caution	Expanded details, caveats
`inward`	Focus, convergence	Summary, synthesis, canonical answer
`outward`	Expansion, discovery	Explore sections, related links
`mixed`	Manga composition rhythm	Hero mosaics only

For English-language Aptlantis Studio pages, forward motion should generally guide the eye from top-left → center → lower-right. Backward motion may be used for archive or historical surfaces, but should not fight the main reading order.

11. Corner Profiles

{ "corner_profiles": ["square", "soft-radius", "single-cut", "dual-cut", "opposite-cut", "all-cut", "asymmetric-soft", "asymmetric-sharp", "manga-irregular", "shard-cut"] }

Corner Profile	Meaning	Best Use
`square`	Stable, plain, archival	Docs, tables, metadata
`soft-radius`	Friendly, approachable	Cards, Q&A, dataset previews
`single-cut`	Technical accent	Badges, cards, utility panels
`dual-cut`	Stronger artifact feel	Download cards, schema cards
`opposite-cut`	Motion and balance	Navigation/process panels
`all-cut`	Compiled artifact container	Highly technical panels
`asymmetric-soft`	Manga-like but readable	Feature cards, section panels
`asymmetric-sharp`	Higher drama	Hero support panels
`manga-irregular`	Full manga composition	Visual mosaics
`shard-cut`	Accent fragment	Small labels, corner flags

Recommended corner offset limits by artifact density:

Density	Max Corner Offset
dense	12px
compact	20px
standard	32px
spacious	48px
hero	72px
visual-only	120px

Generator rule: corner offset must never intrude into the inner safe zone.

12. Safe Zones

Safe zones are mandatory for non-rectangular panels that contain text, numbers, controls, or important icons.

{ "safe_zone_types": ["full-rect", "inset-rect", "inset-polygon", "center-band", "title-band", "stat-grid", "visual-only"] }

{
  "safe_zone": { "type": "inset-rect", "x": 32, "y": 28, "width": 536, "height": 164, "min_text_margin": 24, "preserve_reading_order": true }
}

Rules: text may not render outside the safe zone; click targets may extend outside it only if visible focus states remain clear; decorative glow may enter the bleed zone but not reduce text contrast; badges may sit partly outside the safe zone if they remain readable; visual-only safe zones must not contain essential text.

13. Bleed, Stroke, Glow, And Shadow

outer canvas
  bleed zone
    outer polygon / visible shape
      stroke zone
        inner fill
          safe zone

{ "bleed": { "outer": 12, "allow_glow": true, "allow_shadow": true, "allow_crop": false } }

Glow belongs to state and intensity rules (NIPC/AIC), not arbitrary geometry. APGC defines where glow may appear.

Recommended stroke defaults:

Shape Family	Stroke Style
`rect-stable`	`single-line` or `none`
`soft-card`	`single-line`
`cut-corner`	`corner-accent`
`slant-forward`	`single-line` or `inner-hairline`
`manga-panel-a`	`double-line` or `corner-accent`
`manga-panel-b`	`double-line`
`shard`	`single-line`
`burst`	`broken-technical`

14. SVG Geometry Rules

Use <polygon> for simple four-sided shapes, <path> for cut-corner or mixed geometry, <clipPath> for image/content masks, <mask> only when necessary, and <metadata> for SESM/APGC embedding.

Quadrilateral polygon points are expressed clockwise (top-left → top-right → bottom-right → bottom-left):

{ "outer_polygon": [[0, 16], [580, 0], [600, 204], [20, 220]] }

<svg viewBox="0 0 600 220" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
  <title id="title">Example Manga Panel</title>
  <desc id="desc">A dynamic Aptlantis Studio artifact panel using APGC geometry.</desc>

  <metadata id="sesm"><![CDATA[
  {
    "sesm_version": "0.3.0",
    "asset": { "id": "example-manga-panel", "role": "dataset-card", "title": "Example Manga Panel" },
    "ui": { "component_type": "panel", "preferred_layout": "manga-artifact-panel", "geometry_contract": "apgc-0.1" },
    "extra": {
      "vendor": {
        "aptlantis": {
          "apgc": {
            "contract": "apgc-0.1",
            "shape_family": "manga-panel-a",
            "shape_role": "section-rhythm",
            "angle_energy": 2,
            "skew_direction": "forward",
            "corner_profile": "asymmetric-soft",
            "safe_zone": { "type": "inset-rect", "x": 32, "y": 28, "width": 536, "height": 164 }
          }
        }
      }
    }
  }
  ]]></metadata>

  <defs>
    <clipPath id="panelClip">
      <polygon points="0,16 580,0 600,204 20,220" />
    </clipPath>
  </defs>

  <polygon points="0,16 580,0 600,204 20,220" fill="#111827" stroke="#22D3EE" stroke-width="2" />
  <rect x="32" y="28" width="536" height="164" fill="none" stroke="#64748B" stroke-dasharray="4 6" opacity="0.25" />
</svg>

Generators should support a debug mode that renders safe zones visibly (muted slate stroke, 0.2–0.35 opacity, no fill, small corner control-point dots). Debug safe zones must not appear in production artifacts unless intentionally documented.

15. HTML/CSS Geometry Rules

.apgc-manga-panel-a {
  clip-path: polygon(0% 7%, 96.7% 0%, 100% 92.7%, 3.3% 100%);
}

Every clipped HTML panel must have a fallback shape:

{ "responsive_fallback": "soft-card" }

Fallbacks are required because CSS clipping can create text, focus, overflow, and accessibility problems on small screens.

Width	Geometry Behavior
`>= 1200px`	Full geometry allowed
`900–1199px`	Moderate geometry, reduce offsets by 20%
`640–899px`	Reduce offsets by 40%, preserve safe zone
`< 640px`	Fallback to `soft-card` or `rect-stable`

If a clipped panel contains links or buttons, focus outlines must remain visible and must not be clipped beyond recognition. Recommended: outer wrapper receives focus outline; inner clipped panel receives shape.

16. Shape Selection By Artifact Type

AIC Artifact Type	Default Shape	Allowed Shape Families	Max Energy
`dataset-card`	`soft-card`	`soft-card`, `cut-corner`, `manga-panel-a`	2
`dataset-header`	`trapezoid-wide`	`rect-stable`, `trapezoid-wide`, `manga-panel-a`	3
`pipeline-panel`	`slant-forward`	`cut-corner`, `slant-forward`, `manga-panel-a`	3
`qa-item`	`soft-card`	`soft-card`, `cut-corner`, `slant-forward`	2
`stats-tile`	`rect-stable`	`rect-stable`, `soft-card`, `cut-corner`	2
`theme-board`	`manga-panel-a`	`trapezoid-wide`, `manga-panel-a`, `manga-panel-b`	4
`download-card`	`cut-corner`	`cut-corner`, `slant-forward`	2
`schema-card`	`cut-corner`	`rect-stable`, `cut-corner`	2
`navigation-card`	`slant-forward`	`soft-card`, `slant-forward`, `shard`	3
`archive-summary`	`slant-back`	`rect-stable`, `soft-card`, `slant-back`	2
`brand-promo-panel`	`manga-panel-b`	`manga-panel-a`, `manga-panel-b`, `burst`	5

17. Shape Selection By Semantic Role

Semantic Role / Family	Geometry Reinforcement
`info`, `structure`, `reference`	Rectangular, soft-card, light cut corners
`process`, `pipeline`, `automation`	Forward slants, trapezoids, directional gutters
`success`, `verified`, `reproducible`	Stable shape, small confident badge/shard
`important`, `note`, `decision`	Small shard, rail, folded-corner marker
`critical`, `error`, `blocked`	Controlled cut-corner, never excessive burst by default
`code-heat`, `build`, `operation`	Cut corners, technical notches, orange corner accent
`featured`, `creative`, `discovery`	Manga panels, spotlight frames, asymmetric layouts
`experimental`, `research`, `prototype`	Indigo slants, split panels, hypothesis frames
`archive`, `canonical`, `muted`	Rect-stable, slant-back, low-energy geometry

17.2 Critical Restraint Rule

Red and high angularity should rarely combine — both already signal interrupt/risk, and together they can become visually hostile. Default for critical panels:

{ "shape_family": "cut-corner", "angle_energy": 1, "corner_profile": "single-cut" }

Use burst only for rare, high-level alert graphics. This rule is what NIPC §12 references as the geometry restraint note.

17.3 Yellow Marker Rule

Yellow/attention panels should usually use geometry as a marker (left rail, small shard, folded corner, index marker, badge, underline), not a large container. Avoid large yellow backgrounds, full-panel yellow glow, or multiple yellow shards in one dense view.

18. Manga Mosaic Composition

A manga mosaic is a group of APGC panels arranged as a section, hero, or visual explainer. It should create visual rhythm, preserve reading order, vary panel scale intentionally, use asymmetry without randomness, keep text-safe areas predictable, use gutters as part of the composition, and avoid competing focal points.

{
  "mosaic": {
    "contract": "apgc-0.1",
    "layout_family": "manga-grid-a",
    "reading_order": "top-left-to-bottom-right",
    "gutter": 16,
    "max_angle_energy": 3,
    "panels": [
      { "id": "hero-main", "shape_family": "manga-panel-b", "angle_energy": 3, "role": "primary" },
      { "id": "supporting-stat", "shape_family": "cut-corner", "angle_energy": 1, "role": "support" }
    ]
  }
}

Mosaic layout families: manga-grid-a, manga-grid-b, hero-split-diagonal, rail-and-stack, center-burst-supports, archive-strip, pipeline-flow.

Manga Grid A — balanced feature sections: large primary panel left/top, 2–4 supporting panels right/bottom, moderate slants, clear safe zones.
Manga Grid B — more energetic sections: large angled hero panel, support panels of varied height, stronger diagonal gutters, limited body text.
Hero Split Diagonal — page headers: left identity block, right visual/artifact block, diagonal divider, center-band safe zone.
Rail And Stack — left/right navigation sections: thin vertical trapezoid rail, stacked rectangular or soft-card content panels, small shards for status markers.
Center Burst Supports — rare: central spotlight artifact, small surrounding shards or stat panels, high energy but low text density.
Archive Strip — timelines, snapshots, changelogs: mostly rectangular panels, slant-back accents, muted geometry, horizontal reading flow.
Pipeline Flow — pipeline explanations: forward slanted stage panels, violet process accents, orange execution shards, green verification endpoint.

19. Reading Order Rules

Mosaics must declare reading order when panels are not simple rows:

{ "reading_order": ["hero-main", "metric-records", "pipeline-summary", "download-action"] }

For HTML surfaces, DOM order should follow reading order even if CSS places panels visually. For SVG surfaces, SESM or APGC metadata should preserve intended reading order. Diagonal gutters may point the eye, but should not create ambiguous paths.

20. Density Rules

{ "density": ["dense", "compact", "standard", "spacious", "hero", "visual-only"] }

Density	Text Amount	Max Energy	Safe Zone Requirement
`dense`	High	1	Required
`compact`	Medium	2	Required
`standard`	Medium	2	Required
`spacious`	Low/medium	3	Required
`hero`	Low	4	Required for text
`visual-only`	None/very low	5	Optional

Any panel with body text longer than 240 characters should use rect-stable or soft-card at angle_energy 0-1 (exception: a larger manga-panel-a may be used if the safe zone is rectangular and large enough).

21. Responsive Behavior

Original Shape	Recommended Fallback
`rect-stable`	`rect-stable`
`soft-card`	`soft-card`
`cut-corner`	`soft-card`
`slant-forward`	`soft-card`
`slant-back`	`soft-card`
`trapezoid-wide`	`soft-card` or `rect-stable`
`trapezoid-tall`	`rect-stable`
`manga-panel-a`	`soft-card`
`manga-panel-b`	`soft-card`
`manga-panel-c`	`rect-stable`
`shard`	`badge`
`burst`	`badge` or `soft-card`

Below 640px, text-bearing panels should usually become soft-card or rect-stable. SVG panels should preserve aspect ratio unless the artifact contract explicitly allows cropping.

22. Accessibility Rules

Non-rectangular panels must preserve text contrast, focus visibility, reading order, target size, label clarity, and minimum margins.

A user should not need to perceive shape differences to understand error, warning, success, archive, verified, deprecated, or unavailable — these must be communicated by text, state, ARIA where relevant, metadata, and NIPC semantic color.

APGC may define geometry for motion-like panels, but actual animation belongs to state/intensity rules and must respect reduced-motion preferences.

23. Validation Rules

For production artifacts using APGC:

{ "required": ["contract", "shape_family", "angle_energy", "corner_profile", "safe_zone", "responsive_fallback"] }

For decorative assets, safe_zone may be visual-only.

A validator should check: shape_family is known; angle_energy is within allowed range for the shape family and artifact type; safe zone exists for text-bearing panels; corner offsets do not intrude into safe zone; text regions fit within safe zone; responsive fallback exists; reading order exists for mosaics; critical/error panels do not exceed recommended geometry energy unless explicitly overridden; visual-only panels do not contain essential text.

Warnings should be emitted for: high angle energy + dense text; red semantic role + burst geometry; yellow full-panel container; missing safe zone debug data; shape_family not aligned with artifact type; clip-path panel without focus fallback; mosaic without reading_order; corner offset greater than density limit.

Production generation should fail if: required geometry fields are missing; text-bearing polygon has no safe zone; angle_energy exceeds shape family maximum; angle_energy exceeds artifact maximum without override; outer polygon is invalid; safe zone has negative or impossible dimensions; responsive fallback is missing for HTML clip-path panels.

24. Override Policy

{ "geometry_override": { "enabled": true, "reason": "hero campaign image, visual-only, no essential body text", "approved_by": "design-system" } }

Override should be rare. Recommended reasons: hero campaign visual, one-off infographic, decorative splash asset, experimental theme board, archived legacy mockup.

25. APGC Metadata Placement

APGC fields may appear in: AIC artifact contract files; SESM ui hints; SESM vendor extension fields; generator templates; JSON/TOML theme configuration; SVG <metadata> blocks.

{
  "ui": { "component_type": "panel", "preferred_layout": "manga-artifact-panel", "geometry_contract": "apgc-0.1", "shape_family": "slant-forward", "responsive_behavior": "preserve-safe-zone" }
}

26. Template Naming Conventions

{artifact_type}.{shape_family}.{density}.svg.tmpl

Examples: dataset-card.soft-card.compact.svg.tmpl, dataset-card.cut-corner.compact.svg.tmpl, pipeline-panel.slant-forward.standard.svg.tmpl, theme-board.manga-panel-a.spacious.svg.tmpl, hero.manga-panel-b.hero.svg.tmpl, qa-item.soft-card.compact.svg.tmpl.

Shape tokens should be lowercase and hyphen-separated (manga-panel-a, slant-forward, cut-corner, rect-stable) — avoid MangaPanelA, weirdPanel, coolCyberShape, panel_angled_thing.

27. Recommended Polygon Presets

These presets assume a 600x220 viewBox.

Shape	Outer Polygon	Safe Zone
`rect-stable`	`[[0,0],[600,0],[600,220],[0,220]]`	x24 y24 w552 h172
`cut-corner`	`[[0,0],[576,0],[600,24],[600,220],[24,220],[0,196]]`	x32 y28 w536 h164
`slant-forward`	`[[24,0],[600,0],[576,220],[0,220]]`	x48 y26 w504 h168
`slant-back`	`[[0,0],[576,0],[600,220],[24,220]]`	x48 y26 w504 h168
`trapezoid-wide`	`[[36,0],[564,0],[600,220],[0,220]]`	x56 y30 w488 h160
`manga-panel-a`	`[[0,16],[580,0],[600,204],[20,220]]`	x36 y30 w528 h158
`manga-panel-b`	`[[20,0],[600,28],[560,220],[0,192]]`	x56 y42 w488 h136
`shard`	`[[0,8],[92,0],[108,32],[14,40]]`	x14 y8 w78 h24

28. Implementation Notes For Generators

Generator resolution order: read artifact type from AIC → read semantic role and state from NIPC/AIC/SESM data → determine allowed shape families for artifact type → determine density → choose shape family → clamp angle energy to allowed range → select corner profile → calculate outer polygon → calculate inner safe zone → validate text regions → render SVG or HTML → embed APGC metadata.

Given the same source data, artifact type, theme version, shape family, angle energy, and viewBox, the generator should produce the same geometry every time unless a seed or override is explicitly provided.

Seeded variation (geometry_seed) may alter small corner offsets, panel ordering within an allowed layout family, shard placement, and gutter rhythm — it may not alter required fields, semantic role, state, reading order, or safe zone validity.

29. Page Section Guidance

About / Q&A Pages: qa-item, soft-card, angle_energy 0-1, attention marker as shard or rail.
Pipeline Pages: pipeline-panel, slant-forward, angle_energy 2, skew_direction: forward.
Dataset Pages: dataset-header uses trapezoid-wide at angle_energy 2; dataset-card stays calmer at soft-card/cut-corner, angle_energy 0-1.
Theme Boards: manga-panel-a, angle_energy 2-3 — theme boards may use more expressive geometry because they demonstrate the visual system.
Marketing / Hero Sections: manga-panel-b, angle_energy 3-4, safe zone center-band or title-band. Avoid long paragraphs inside high-energy hero panels.

30. Opinionated Defaults

Default panels are rectangles or soft cards.
Important panels may use cut corners.
Process/navigation panels may slant forward.
Archive/history panels may slant backward.
Hero mosaics may use manga-panel variants.
Dense text must always preserve an inner rectangular safe zone.
Extreme angles are only for mostly visual artifacts.
Geometry must never be the only carrier of meaning.
Color meaning comes from NIPC.
Artifact structure comes from AIC.
Embedded meaning comes from SESM.
Brand expression comes from Neon Ink.
Visual rhythm comes from APGC.

31. Architecture Summary

Source Data / Manifest
  ├── SESM Meaning        → Identity / Provenance / Links
  ├── AIC Artifact Contract → Fields / Regions / Render Targets
  ├── NIPC Palette Contract → Hue / Family / Intent / Intensity
  ├── APGC Geometry Contract → Shape / Corners / Angles / Safe Zones
  └── Neon Ink Expression  → Typography / Voice / Page Rhythm
        ↓
Compiled SVG / HTML Artifact

32. Minimal APGC Contract Example

{
  "apgc_version": "0.1.0",
  "artifact_type": "dataset-card",
  "shape_family": "cut-corner",
  "shape_role": "artifact-container",
  "angle_energy": 1,
  "skew_direction": "none",
  "corner_profile": "single-cut",
  "outer_shape": "polygon",
  "outer_polygon": [[0,0],[576,0],[600,24],[600,220],[24,220],[0,196]],
  "safe_zone": { "type": "inset-rect", "x": 32, "y": 28, "width": 536, "height": 164, "min_text_margin": 24 },
  "bleed": { "outer": 12, "allow_glow": true, "allow_shadow": true },
  "responsive_fallback": "soft-card",
  "validation": { "preserve_reading_order": true, "max_corner_offset": 24, "requires_safe_zone": true }
}

33. Full Artifact Integration Example

{
  "aic_version": "0.1.0",
  "artifact_type": "pipeline-panel",
  "required": ["pipeline_id", "state", "stage_list", "updated"],
  "layout": { "regions": ["title", "stage_list", "status", "timestamp", "actions"], "density": "standard", "geometry_contract": "apgc-0.1", "safe_zone_required": true },
  "theme": { "id": "neon-ink", "semantic_role": "pipeline", "semantic_family": "process-transformation", "state": "running", "intensity": 3 },
  "geometry": {
    "contract": "apgc-0.1",
    "shape_family": "slant-forward",
    "shape_role": "forward-motion",
    "angle_energy": 2,
    "skew_direction": "forward",
    "corner_profile": "opposite-cut",
    "safe_zone": { "type": "inset-rect", "x": 48, "y": 26, "width": 504, "height": 168 },
    "responsive_fallback": "soft-card"
  }
}

34. Versioning

MAJOR: breaking shape contract changes
MINOR: new shape families, optional metadata, additive validation
PATCH: wording, examples, clarifications

{ "apgc_version": "0.1.0" }

35. Summary

APGC makes shape a first-class part of the Aptlantis Studio design system. It allows manga-informed quadrilateral panels, slants, cuts, shards, trapezoids, and mosaics without drifting into arbitrary decoration.

SESM = embedded meaning
NIPC = color meaning
AIC = artifact structure
Neon Ink = brand expression
APGC = geometry rhythm

APGC should let Aptlantis Studio become more visually distinctive while remaining deterministic, accessible, static-friendly, archive-aware, and generator-ready.

1. Overview​

2. Relationship To Existing Specs​

3. Goals​

4. Non-Goals​

5. Design Philosophy​

5.1 Rectangles Are Still Valid​

5.2 Manga Energy Without Manga Confusion​

5.3 Shape Is Rhythm, Not Truth​

5.4 Geometry Should Reduce Drift​

6. Terminology​

7. Core Geometry Model​

8. Shape Families​

9. Angle Energy Scale​

10. Directional Semantics​

11. Corner Profiles​

12. Safe Zones​

13. Bleed, Stroke, Glow, And Shadow​

14. SVG Geometry Rules​

15. HTML/CSS Geometry Rules​

16. Shape Selection By Artifact Type​

17. Shape Selection By Semantic Role​

17.2 Critical Restraint Rule​

17.3 Yellow Marker Rule​

18. Manga Mosaic Composition​

19. Reading Order Rules​

20. Density Rules​

21. Responsive Behavior​

22. Accessibility Rules​

23. Validation Rules​

24. Override Policy​

25. APGC Metadata Placement​

26. Template Naming Conventions​

27. Recommended Polygon Presets​

28. Implementation Notes For Generators​

29. Page Section Guidance​

30. Opinionated Defaults​

31. Architecture Summary​

32. Minimal APGC Contract Example​

33. Full Artifact Integration Example​

34. Versioning​

35. Summary​