guizang-social-card-skill/references/components.md

Components

Shared component spec for both seed templates. Read this when you need to look up a class, a font size, or a hard rule that recurs across recipes. Per-recipe details live in layout-recipes.md; per-theme color tokens live in theme-presets.md.

Font Stacks

Editorial Magazine x E-ink (template-editorial-card.html):

• --serif-zh: Noto Serif SC, Songti SC, STSong — display titles.
• --serif-en: Playfair Display, italic for subtitles and pull quotes.
• --sans-zh: Noto Sans SC, PingFang SC — utility text and fallback; body and lead default to serif-zh in Editorial.
• --sans-en: Inter — Latin body in mixed content.
• --mono: IBM Plex Mono — labels, page metadata, issue strip, captions.

Swiss International (template-swiss-card.html):

• --sans: Inter, Helvetica Neue, Helvetica.
• --sans-zh: Noto Sans SC, PingFang SC — Chinese body.
• --mono: IBM Plex Mono — labels, captions, t-meta.

Never load a serif font in the Swiss template. Never let the Editorial template lose its serif display family.

Type Scale + Weight Mapping

Both templates follow the rule "the larger, the lighter." Small text always uses heavier weight than large text. On 1080x1440 boards, the minimum readable size is 22-28px after factoring in mobile downsample.

Editorial scale (default for 3:4):

Role	Class	Size	Weight	Tracking	Family
Display	.h-display	124px	500	+.04em	serif-zh
Section ttl	.h-xl	88px	500	+.03em	serif-zh
Mid title	.h-md	56px	500	+.02em	serif-zh
Subtitle	.h-sub	36px	400 it	normal	serif-en
Pull quote	.pullquote	64px	500 it	normal	serif-zh
Lead	.lead	28px	400	normal	serif-zh
Body	.body	24px	400	normal	serif-zh
Kicker	.kicker	21px	500	+.22em	mono
Meta	.meta	18px	500	+.20em	mono
Label	.label	18px	500	+.20em	mono

Restored 2026-05-27. The previous defaults (900 / 700 / 700 / sans body / −.01em) made Editorial cards read as heavy infographic banners. They are NOT the Guizang showcase aesthetic — see local-tests/demo-showcase/editorial.html for the source-of-truth. The rule is restrained typography: light weights, serif body italic-tolerant, wide tracking on display + mono. Heaviness in Editorial = visual demotion to "generic landing-page", same trap as Swiss.

Swiss scale (default for 3:4):

Role	Class	Size	Weight	Family
Hero	.h-hero	240px	200	sans
Statement	.h-statement	180px	200	sans
Section ttl	.h-xl	120px	300	sans
Mid title	.h-md	56px	400	sans
Mega number	.num-mega	200px	200	sans
XL number	.num-xl	144px	200	sans
Lead	.lead	30px	400	sans-zh
Body	.body	26px	400	sans-zh
Category	.t-cat	22px	600	sans
Meta	.t-meta	20px	500	mono
Caption	.swiss-img-caption	18px	500	mono

Both templates auto-shrink display sizes inside .poster.square and .poster.wide. You usually do not override them. Override only when a single title cannot be shortened further.

Chinese Title Length Bands

Chinese characters are visually denser than Latin. Pick a band before sizing:

Title shape	Editorial display	Swiss h-hero
1 line, <= 6 Chinese chars	132px (default)	240px (default)
1 line, 7-10 chars	108px	200px
2 lines, each <= 8 chars	96px	180px
2 lines, any line 9-12 chars	84px	152px
3 lines (rare)	72px	132px

If the title still does not fit, shorten the copy first. Never solve overflow by shrinking body text below the minimum readable size.

Swiss .h-xl — Hard Caps per Board (validated)

The seed template ships these caps. Anything more violates the vertical budget — verified empirically in local-tests/smoke-ai-tools/:

Board	Default .h-xl	Max lines	Max chars / line	What happens past the cap
.poster.xhs (1080×1440)	96px	2	8	3-line title pushes ledger/matrix past 1440 — push content off-canvas
.poster.square (1080×1080)	88px	2	7	Bottom card or metadata strip clips
.poster.wide (2100×900)	104px	1	14	Wraps to 2 lines and crowds the right column

If your title needs 3 Chinese lines on .poster.xhs: switch the recipe from S03/S10/S12 (data-heavy) to S01/S05 (cover-style) where the title can dominate. Don't shrink .h-xl below 80px — small + heavy reads as Web1.0.

Editorial .h-xl — Hard Caps per Board (validated)

The Editorial seed default for .h-xl is 88px serif weight 500. Verified in local-tests/demo-smoke-editorial-travel/ on M11/M14/M07 with 3-paragraph body + ledger + 5-step pipeline:

Board	Default .h-xl	Max lines	Max chars / line	What happens past the cap
.poster.xhs (1080×1440)	88px	2	9	3 lines push the marginalia / ledger / pipeline rows past the issue strip
.poster.square (1080×1080)	78px	2	8	Sub-paragraph or pull-quote clips
.poster.wide (2100×900)	96px	1	16	Wraps and crowds the marginalia column

The smoke deck's p2 title 第三次进山,装备比上一次轻 3.4kg is the 2-line × 9-char limit and worked. The <br> was load-bearing — let CJK auto-wrap freely on .h-xl and you get awkward breaks. Hard-break manually at semantic seams.

Per-recipe nuance:

• M11 (Marginalia Essay): 2-line title leaves room for 3 paragraphs of 3-4 sentences each in a 700px main column, and 5-7 marginalia rows in a 220px aside.
• M14 (Vertical Pipeline): 2-line title + 5 steps (each step-title 42px serif + step-desc 26px sans, 28px gap) hits the 1440 floor exactly — adding a 6th step requires shrinking title to 1 line.
• M07 (Field Ledger): 2-line title + 5 ledger rows with both .ledger-title and .ledger-note ≈ 100-120px row height — exactly fills. 6 rows requires 1-line title.

Matrix + hero-stat-bottom on .poster.xhs

.matrix-fill with grid-auto-rows: min-content is the safe default on xhs. Hard limits:

Cells	Rows	Pair with hero-stat-bottom?	Notes
4	2	Yes — comfortable	Cells get 200+ px each
6	3	Yes — recommended	The sweet spot
8	4	Only with shortened title + num-mega 110-128px	Compressed; do not also use 3-line title
10+	5+	No	Use S10 H-Bar Chart instead — that pattern scales

Minimum Readable Sizes (mobile-safe)

A 1080x1440 PNG is usually viewed on a phone at 360-420 logical pixels wide. Anything below the listed size becomes unreadable:

Role	Minimum	Notes
Body / paragraph	28px	Editorial, Swiss alike
Lead	30px	The "1.5x body" guard
Caption / kicker	20px	Do not drop below 18px
Label / meta strip	20px	Mono only
Cell title in grids	24px	Matrix / brief cards
Number annotation	22px	Stat-card .lbl, ledger .sub

If you cannot fit the copy, cut the copy. Do not shrink type.

Card Fills — Swiss Only, Mutually Exclusive

Four card classes exist; never combine them on the same node:

• .card-ink — solid black ink, paper text. Use for one statement card.
• .card-accent — accent fill, accent-on text. Use sparingly; max one accent card per poster.
• .card-fill — grey-1 fill, ink text. The workhorse for matrix / brief / takeaway grids.
• .card-outlined — transparent + 1px grey-2 border, ink text. Use when you need a card without weight.

Multi-card grids must use the same card class for every cell, except a single accent highlight is allowed when one item is meant to stand out. Mixing card-fill with card-outlined in the same grid looks like sloppy templating.

The Editorial template intentionally does not provide card classes. Editorial layouts express hierarchy through type, rules, ledger rows, and column structure — not card backgrounds. If you find yourself wanting a card on an Editorial poster, you probably picked the wrong style mode.

Image Containers

Both templates share the same .frame-img system. Always pick a standard ratio class. Never write aspect-ratio: 2592/1798 style ad-hoc ratios.

Class	Ratio	Use
.r-3x4	3 : 4	Default for portrait covers and field-note photos.
.r-1x1	1 : 1	Square portraits, product objects, balanced grids.
.r-4x3	4 : 3	Classic editorial photo, full-bleed top zone.
.r-3x2	3 : 2	Magazine inline figure.
.r-16x9	16 : 9	Landscape photo, infographic.
.r-16x10	16 : 10	Default for left-text + right-image splits.
.r-21x9	21 : 9	WeChat 21:9 hero image, S08 Image Hero top zone.

Default object-fit: cover keeps object-position: center 50% (both templates). Use .fit-contain for UI screenshots, dense text, code, and infographics. Do not crop faces or product key features.

Subject-aware cropping — always set object-position inline per photo. The template default is a fallback, not a recommendation. Before each <img>, look at the source and ask: where is the subject? Then set style="object-position:center N%" on the <img> directly:

Subject location in source	Inline value
Subject near top (sky-heavy landscape, face at top)	center 25-35%
Subject centered (default)	center 50% (omit, it's the default)
Subject mid-body (hiker, hands, mid-frame)	center 55-65%
Subject low (foreground gear, ledger, foot of frame)	center 70-80%

The default center 50% will silently crop subjects out of frame on tall ratios (r-3x4, r-21x9). Every photo in a delivered package needs a deliberate object-position — even if the conclusion is "50% is fine here." Catch this in the render-check pass: if the subject is more than 1/3 outside the visible crop, fix it before delivering.

Caption class name (don't get this wrong):

• Editorial template: .img-cap — 18px mono, applied to <figcaption> under .frame-img. Writing .cap falls back to browser-default 16px and trips R4.
• Swiss template: .swiss-img-caption — same role, 18px mono.

There is no shared .cap class. If you see .cap in a draft, fix it before render.

Screenshot Containers (.frame-shot)

For UI screenshots / web captures / code shots, use .frame-shot (both seeds carry it). It defaults to object-fit: contain so the source pixels stay pristine — the opposite of .frame-img. See references/screenshot-treatment.md for the full parameter matrix.

Quick summary of style-locked defaults (don't second-guess these):

Style	Corners	Shadow	Default bg	Default inset
Swiss	corners-sq	shadow-none	bg-grey-1	inset-sub
Editorial	corners-sm	shadow-soft	bg-paper-2	inset-sub

Two device wrappers (.device-browser, .device-phone) ship in both templates and provide CSS-only browser chrome / phone bezel — no SVG, no image deps. Wrap one .frame-shot per chrome.

Map Block (.map-block)

For content with spatial relationships (routes, neighborhoods, store locations). Both seeds ship .map-block + .map-pin + .map-legend. Pick the map source by how literal the location needs to be — see references/map-component.md for the full playbook:

• Mode T (default for travel / route / wayfinding) — Mapbox Static Images API URL as <img> source; needs MAPBOX_ACCESS_TOKEN. Apply tone-paper (Editorial) or tone-paper saturation-0 (Swiss).
• Mode O — OSM static tile composite, fallback when no Mapbox token is available and the map still needs to be geographically real.
• Mode S — schematic SVG drawn in viewBox="0 0 100 100" for conceptual or abstract relation maps only.

Hard limits: ≤6 pins per board, ≤1 accent pin, no SVG text labels (names go in .map-pin .card).

Spacing Tokens (Swiss only)

Swiss template exposes a Carbon-style 2x scale. Stick to these tokens — arbitrary px margins drift fast across posters.

Token	Value	Typical use
--sp-3	8px	Tight chip gap, inline meta spacing.
--sp-4	12px	Card inner gap, dense list rows.
--sp-5	16px	Body block bottom margin, lead-to-paragraph.
--sp-6	24px	Card padding (compact), grid gap (tight).
--sp-7	32px	Default grid gap.
--sp-8	40px	Card padding (default), section gap (compact).
--sp-9	48px	Section gap (default), pair-preview outer padding.
--sp-10	64px	Major break between content blocks on portrait.
--sp-11	80px	Poster outer padding (square / wide).
--sp-12	96px	Poster outer padding (portrait).
--sp-13	160px	Wide poster horizontal padding only.

Editorial template uses bare px for now because magazine layouts often want bespoke spacing for atmosphere. If you find a pattern that recurs, add an editorial token here.

Icons

Default icon library is Lucide (loaded only by the Swiss template). Editorial layouts rarely need icons; when they do, use the same Lucide set, but limit to one or two per poster.

Rules:

• No emoji anywhere. Emojis ruin both styles.
• Use angular Lucide icons (arrow-right, check, triangle-alert, dot, plus, equal, slash). Avoid pillow-rounded icons (smile, heart-filled) — they fight Swiss geometry.
• Icon stroke weight: 1.5 (Lucide default). Do not thicken.
• Size: 56px for ledger row indicators, 32px inline with body, 24px in chips. Never below 20px.
• Color: var(--accent) for highlight, var(--grey-3) for neutral, var(--ink) for primary. Never gradient.

To add an icon:

<i data-lucide="arrow-right" width="32" height="32"></i>

The Swiss template runs lucide.createIcons() on load. If you inject icons after load, call it again manually.

Issue Label and Corner Metadata

Social cards do not have PPT's chrome/foot dual-row metadata. They use a single, quiet element instead.

Editorial issue elements:

• .issue-row — top: "Vol. 01 · 2026.05" with a small accent dot between segments.
• .issue-strip — bottom band: 3-5 short labels separated by em-dashes, above a hairline.

Swiss issue elements:

• .chrome-min — top single row with category on left, date/issue on right, bottom hairline.
• .t-meta — inline mono uppercase metadata anywhere on the poster.

One issue element per poster. Never both top issue strip and bottom issue strip on the same poster — it looks like decoration.

Layout Primitives

Both templates share the same primitives (different default gaps).

Class	Editorial gap	Swiss gap	Use
.stack	flex column	flex column	Default vertical flow.
.row	flex row	flex row	Horizontal flow.
.gap-1...-5	12-64px	8-16px	Editorial gaps (px) vs Swiss (token).
.gap-6...-10	n/a	24-64px	Swiss only — Carbon scale.
.col-2-7-5	7:5 split	n/a	Editorial only — quote + image.
.col-2-8-4	8:4 split	n/a	Editorial only — text-heavy + image.
.grid-12	n/a	12-col grid	Swiss only.
.span-N	n/a	grid column span	Swiss only.
.grid-3	3 columns	3 columns	Both.

Hard Rules (Shared)

These rules guard the visual identity. Violations are almost always wrong.

1. Pick exactly one style mode per package. Never mix Editorial and Swiss.
2. Pick exactly one theme/accent per package. Never combine two palettes.
3. No emojis, ever. Use Lucide or restrained type.
4. No fake data, no fake percentages, no Lorem text in delivered output.
5. No border-radius, box-shadow, or linear-gradient in Swiss.
6. No flat one-color background in Editorial — paper grain + optional WebGL atmosphere is required on hero / quote / sparse pages.
7. Every .poster must have stable export dimensions. Never use vw / vh in poster content.
8. Every image must be wrapped in .frame-img with a standard ratio class.
9. Multi-card grids use one card class. One accent card maximum.
10. Honor the type scale and minimum sizes. Cut copy before shrinking type.