vndangkhoa/open-design
1
0
Fork 0
mirror of https://github.com/nexu-io/open-design.git synced 2026-05-31 19:04:39 +07:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
open-design/craft
History
Mohamed Abdallah be1b3dae40
craft: add rtl-and-bidi so OD artifacts don't break for Arabic / Hebrew / Persian users (#595) 
* feat(craft): add rtl-and-bidi + opt-ins on blog-post, docs-page, finance-report

Module 4 of 5 in the behavioral craft series proposed in #501. Modules
1 (state-coverage, #502) and 2 (animation-discipline, #515) merged.
Module 3 (accessibility-baseline, #587) open at time of authoring.

Differentiating niche per the corpus prior-art survey: zero existing
OSS RTL skill is Apache-2.0, framework-agnostic, and aligned with
UAX #9 rev 51. The closest comparators (idanlevi1/rtlify 5★, MIT;
skills-il/localization 7★, MIT) are LTR-web-skewed and don't cover
Flutter Directionality, RN I18nManager, Compose LocalLayoutDirection,
or iOS UIKit semanticContentAttribute / SwiftUI layoutDirection.

Three-loop adversarial review pass via Claude Opus 4.7 xhigh effort
(codex unavailable). Loop 1 caught five revisions (typography spin-out,
WebKit prose compression, mistakes-list trim 12→9, alreq letter-spacing
rename dropped, WebKit r94775 specific revision dropped). Loop 2 caught
one blocking SwiftUI 4 claim and three nits. Loop 3 said ship.

Skill opt-ins picked to avoid PR #587 merge surface: blog-post (long-form
text), docs-page (LTR code islands in RTL prose), finance-report
(numerals + IBAN + currency).

Refs #501.

* fix(craft): rtl-and-bidi review fixes (lefarcen 6 findings)

- P2 #1 WebKit #50949: bug is RESOLVED FIXED, not still open. Verified
  directly against bugs.webkit.org. Removed the broken-WebKit framing;
  the recommendation to prefer <bdi> over CSS now stands on UAX #9
  §2.7 ("prefer markup over CSS or control characters") rather than a
  WebKit bug. Source list updated to drop the dead reference.
- P2 #2 isolate vs embedding controls: U+202C PDF is the
  embedding/override terminator, not an isolate terminator. Split into
  two families: isolate controls (U+2066/2067/2068 + U+2069 PDI) for
  modern code, embedding/override controls (U+202A/202B/202D/202E +
  U+202C PDF) as legacy. Recommend isolates first.
- P2 #3 base direction and language: new section covering
  <html dir lang>, mixed-language subtrees, dir=auto for UGC. Without
  this, agents can follow every other rule and still ship an LTR
  document containing Arabic.
- P2 #4 phone/IBAN/card values: bare <bdi> is unreliable for
  weak/neutral character runs; updated must-mirror bullet and forms
  section to require <bdi dir="ltr">. Added common-mistake entry.
- P3 #1 native mobile budget: added a one-line opt-out hint at the
  top of the section so HTML-only skills know they can skim it. Full
  split into web/native files deferred — the table is 16 lines on a
  176-line file, the cost is bounded.
- P3 #2 lintability: restructured "common mistakes" into three groups
  — mechanically lintable, needs script detection, HTML semantics —
  with explicit exception language (chart axes, physical-object icons,
  platform-pinned UI). Avoids false positives in future linting.

Reviewed via Claude CLI Opus 4.7 xhigh effort (3 loops on the
original draft); these fixes are explicit reviewer responses with
WebKit Bugzilla state verified live.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(craft): rtl-and-bidi mrcfps round-2 precision (lang+dir, isolate picks)

Two non-blocking precision items:

- lang-without-dir scope: previous wording implied English never needs
  dir="ltr". True only at the document root in a default-LTR page.
  lang does not reset an inherited bidi base direction, so an
  <section lang="en"> inside an RTL ancestor still resolves RTL.
  Reworded to "lang without dir is fine at the document root in a
  default-LTR page; inside any opposite-direction ancestor, set both."
- Plain-text isolate picks: previous wording recommended U+2068 / U+2069
  generically. U+2068 is FSI (first-strong auto-detect) — wrong default
  for known-direction runs, especially weak/neutral-heavy values like
  phone, IBAN, card numbers (the same class this file forces to LTR in
  HTML). Split: LRI/PDI for known-LTR, RLI/PDI for known-RTL, FSI/PDI
  reserved for unknown direction. Added an explicit "don't default to
  FSI" callout.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(craft+skills): rtl-and-bidi mrcfps round-3 — skill-body conflicts + bidi semantic correction

P1 BLOCKING — skill-body physical-direction conflicts (mrcfps):

- skills/docs-page: "left nav" / "right-rail TOC" / "left-edge accent
  stripe" survive in skill body even with the rtl-and-bidi opt-in,
  because craft is injected ABOVE the skill body. An Arabic docs
  request would still see "Left nav" and emit physical-direction
  layout. Updated description, lay-out section, and self-check to
  inline-start / inline-end vocabulary; added a self-check bullet
  requiring logical CSS on rails and accent.

- skills/blog-post: pull-quote "accent rule on the left" updated to
  "accent rule on the inline-start edge" with a matching note about
  flipping under dir="rtl".

P1 craft semantic correction (mrcfps):

- HTML-semantics lint: previous wording equated <bdi dir="auto"> with
  unicode-bidi: plaintext. Not equivalent. <bdi> isolates an inline
  run from surrounding bidi resolution; unicode-bidi: plaintext
  changes how base direction is *determined* for each plaintext
  paragraph in a block. Different surfaces. Reworded the lint guidance
  to "prefer semantic isolation in HTML for inline runs; reach for
  unicode-bidi: plaintext only when that block-level paragraph
  behavior is explicitly required and tested" — and explicitly flagged
  that they are not drop-in equivalents to avoid future linters
  flagging valid CSS with a non-equivalent fix.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(craft): rtl-and-bidi mrcfps round-4 — split progress-bar from media scrubber

Non-blocking precision: prior must-mirror bullet lumped "progress-bar
fill" together with sliders, which would have flipped a video / audio
scrubber under dir="rtl" — directly conflicting with the must-not-mirror
rule for media playback controls (play/pause/FF/rewind represent tape
direction, not reading direction). The two cases collide on every audio
or video player.

- Must-mirror progress bars now scoped to "non-media" (download, upload,
  form-completion).
- Media scrubber / progress timeline added explicitly to the must-not-
  mirror media bullet.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-06 12:43:48 +08:00
..
accessibility-baseline.md feat(craft): accessibility-baseline module + opt-ins on dashboard, hr-onboarding, mobile-onboarding (#587) 2026-05-06 09:18:59 +08:00
animation-discipline.md feat(craft): animation-discipline module + opt-ins on mobile-app, mobile-onboarding, gamified-app (#515) 2026-05-05 18:32:30 +08:00
anti-ai-slop.md feat(craft): add brand-agnostic craft references + Refero-derived lint rules (#225) 2026-05-02 11:00:33 +08:00
color.md feat(craft): add brand-agnostic craft references + Refero-derived lint rules (#225) 2026-05-02 11:00:33 +08:00
README.md craft: add rtl-and-bidi so OD artifacts don't break for Arabic / Hebrew / Persian users (#595) 2026-05-06 12:43:48 +08:00
rtl-and-bidi.md craft: add rtl-and-bidi so OD artifacts don't break for Arabic / Hebrew / Persian users (#595) 2026-05-06 12:43:48 +08:00
state-coverage.md feat(craft): state-coverage module + opt-ins on dashboard, mobile-app, kanban-board (#502) 2026-05-05 16:31:05 +08:00
typography.md feat(craft): add brand-agnostic craft references + Refero-derived lint rules (#225) 2026-05-02 11:00:33 +08:00

README.md

Craft references

Brand-agnostic craft knowledge. Each file is a small, dense rulebook on one dimension of professional UI craft (typography, color, motion, …). Skills opt into the references they need; the daemon injects only the requested ones into the system prompt above the active skill body.

Why a third axis next to skills/ and design-systems/

Axis Scope Example
skills/ Artifact shape saas-landing, dashboard, pricing-page
design-systems/ Brand visual language (the 9-section DESIGN.md) linear-app, apple, notion
craft/ Universal craft knowledge — true regardless of brand letter-spacing rules, accent-overuse caps, anti-AI-slop

DESIGN.md tells the agent which colors and fonts a brand uses. craft/ tells the agent the universal rules a competent designer applies on top — e.g. ALL CAPS always needs ≥0.06em tracking, regardless of the brand.

How a skill opts in

Add an od.craft.requires array to the skill's front-matter. Only the listed sections are injected, so a skill that needs only typography pays no token cost for color/motion content.

od:
  craft:
    requires: [typography, color, anti-ai-slop]

Allowed values match the file names in this directory minus the .md extension. Unknown values are silently ignored (forward-compatible).

Why silent fallback instead of fail-fast?

A skeptical reader will ask: "If a skill requests a planned-but-not-yet-vendored section and the corresponding file doesn't exist yet, shouldn't we warn the user?" We chose forward-compatibility over fail-fast: a skill authored today can list a planned slug and start benefiting the moment the matching craft/<slug>.md is vendored in a follow-up PR, with no skill edit needed. The cost of a missed reference is a missing paragraph in the system prompt, not a broken skill — so the loud failure mode is not worth the friction.

Note for skill authors arriving from older guidance: an earlier draft used motion as the future-slug placeholder. The shipped equivalent today is animation-discipline. Use that one if your skill emits motion.

Enforcement levels

Craft files mix auto-checked rules and guidance.

  • Auto-checked. Rules wired into apps/daemon/src/lint-artifact.ts — currently the P0 list in anti-ai-slop.md (Tailwind-indigo accent, two-stop hero gradients, emoji-as-icons, etc.). The linter reports these as findings back to the UI (for P0/P1 badges) and to the agent (as a system reminder for self-correction). Artifact persistence is not currently hard-blocked on P0 hits.
  • Guidance. The rest. The agent reads the rules, reviewers apply them, the linter doesn't check them.

A purely behavioral craft file (state-coverage, animation-discipline) is guidance unless a specific rule is later promoted into lint-artifact.ts.

Files

File Section name When to require
typography.md typography Any skill that emits typed content (~all skills)
color.md color Any skill that emits styled output (~all skills)
anti-ai-slop.md anti-ai-slop Marketing pages, landing pages, decks
state-coverage.md state-coverage Any skill with stateful UI (dashboards, mobile apps, forms, list/table views)
animation-discipline.md animation-discipline Any skill that ships motion: mobile apps, multi-screen flows, gamified UI, transitions, microinteractions
accessibility-baseline.md accessibility-baseline Any skill that ships interactive UI: dashboards, forms, mobile flows, anything with focus/labels/keyboard paths
rtl-and-bidi.md rtl-and-bidi Any skill that ships localized text or layout: blogs, docs, financial tables, mobile apps, anything that may render Arabic / Hebrew / Persian

Partial-stateful skills. A skill that's mostly static but contains an embedded form, data table, or query surface should opt in. State-coverage rules apply to the stateful component, not the whole page.

More sections (icons, craft-details) will be added in follow-up PRs as we wire the linter side.

Attribution

Craft content is adapted from the MIT-licensed refero_skill project (© Refero Design), with edits to fit Open Design's house style and link back to OD's design tokens (var(--accent) etc.) instead of generic Tailwind hex values.