medesign 0.0.0-stage → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +128 -2
  3. package/bin/medesign.js +200 -0
  4. package/integrations/claude-code/SKILL.md +20 -0
  5. package/integrations/cursor/medesign.mdc +26 -0
  6. package/medesign.config.js +46 -0
  7. package/package.json +62 -4
  8. package/presets/apple/design-tokens.css +115 -0
  9. package/presets/apple/guidelines.md +19 -0
  10. package/presets/apple/preset.json +53 -0
  11. package/presets/metha/design-tokens.css +127 -0
  12. package/presets/metha/guidelines.md +23 -0
  13. package/presets/metha/preset.json +53 -0
  14. package/presets/schema.json +102 -0
  15. package/presets/tesla/design-tokens.css +112 -0
  16. package/presets/tesla/guidelines.md +17 -0
  17. package/presets/tesla/preset.json +53 -0
  18. package/references/ai-tells.md +127 -0
  19. package/references/appendices.md +220 -0
  20. package/references/architecture.md +39 -0
  21. package/references/argon-design-archetypes.md +317 -0
  22. package/references/banner-sizes-and-styles.md +118 -0
  23. package/references/block-library.md +61 -0
  24. package/references/brand-design-tokens.md +42 -0
  25. package/references/catalog.json +108 -0
  26. package/references/cip-deliverable-guide.md +95 -0
  27. package/references/cip-design.md +121 -0
  28. package/references/cip-prompt-engineering.md +84 -0
  29. package/references/cip-style-guide.md +68 -0
  30. package/references/cli-architecture.md +146 -0
  31. package/references/components.md +240 -0
  32. package/references/dark-mode.md +23 -0
  33. package/references/design-core.md +42 -0
  34. package/references/design-md-protocol.md +75 -0
  35. package/references/design-routing.md +207 -0
  36. package/references/eng-imagery-content.md +71 -0
  37. package/references/eng-layout.md +28 -0
  38. package/references/eng-other.md +26 -0
  39. package/references/eng-states-theme.md +22 -0
  40. package/references/eng-type-color.md +44 -0
  41. package/references/icon-design.md +122 -0
  42. package/references/image-mockup-direction.md +53 -0
  43. package/references/image-to-code.md +46 -0
  44. package/references/impeccable-polish.md +85 -0
  45. package/references/intake.md +90 -0
  46. package/references/logo-color-psychology.md +101 -0
  47. package/references/logo-design.md +110 -0
  48. package/references/logo-prompt-engineering.md +158 -0
  49. package/references/logo-style-guide.md +109 -0
  50. package/references/mesurv-dna.md +104 -0
  51. package/references/micro-interactions-and-auto-animate.md +71 -0
  52. package/references/modern-craft-invariants.md +332 -0
  53. package/references/motion-tokens.md +99 -0
  54. package/references/preflight.md +110 -0
  55. package/references/proactive-motion.md +167 -0
  56. package/references/quality-gate.md +147 -0
  57. package/references/redesign-audit.md +38 -0
  58. package/references/redesign.md +52 -0
  59. package/references/slides-copywriting-formulas.md +84 -0
  60. package/references/slides-create.md +4 -0
  61. package/references/slides-html-template.md +295 -0
  62. package/references/slides-layout-patterns.md +137 -0
  63. package/references/slides-strategies.md +94 -0
  64. package/references/slides.md +42 -0
  65. package/references/social-photos-design.md +329 -0
  66. package/references/spatial-canvas-engine.md +160 -0
  67. package/references/stitch-system.md +184 -0
  68. package/references/style-extraction.md +17 -0
  69. package/references/styles/brutalist.md +88 -0
  70. package/references/styles/minimalist.md +81 -0
  71. package/references/styles/soft.md +94 -0
  72. package/references/threeui-spatial-engine.md +224 -0
  73. package/references/ui-styling-shadcn.md +336 -0
  74. package/references/ui-ux-vocabulary-vault.json +1223 -0
  75. package/references/ui-ux-vocabulary-vault.md +438 -0
  76. package/references/vocab-protocol.md +52 -0
  77. package/references/vocabulary.md +78 -0
  78. package/scripts/export-tokens.js +403 -0
  79. package/tests/browser-audit.js +442 -0
  80. package/tests/linter.js +412 -0
  81. package/tests/schemas/sarif-2.1.0.schema.json +2915 -0
  82. package/tests/visual-testbed.html +681 -0
@@ -0,0 +1,108 @@
1
+ {
2
+ "version": "1.0.0",
3
+ "name": "medesign-catalog",
4
+ "archetypes": [
5
+ {
6
+ "id": "cyber-saas",
7
+ "name": "Cyber-SaaS & Stark Ink",
8
+ "inspiration": ["Vercel", "Linear", "Supabase", "Mintlify"],
9
+ "tokens": {
10
+ "canvas_light": "#fafafa",
11
+ "canvas_dark": "#0a0a0a",
12
+ "ink_primary": "#171717",
13
+ "ink_primary_dark": "#ededed",
14
+ "hairline_border": "rgba(255, 255, 255, 0.08)",
15
+ "hairline_border_light": "rgba(0, 0, 0, 0.08)",
16
+ "mesh_gradient": "radial-gradient(ellipse 80% 50% at 50% -20%, rgba(120, 119, 198, 0.15), transparent)",
17
+ "heading_tracking": "-0.035em",
18
+ "button_radius": "9999px",
19
+ "card_radius": "14px"
20
+ },
21
+ "shadows": {
22
+ "card": "0 0 0 1px rgba(255, 255, 255, 0.08) inset, 0 12px 32px -8px rgba(0, 0, 0, 0.5)",
23
+ "button": "0 0 0 1px rgba(255, 255, 255, 0.15) inset, 0 2px 8px rgba(0, 0, 0, 0.12)"
24
+ }
25
+ },
26
+ {
27
+ "id": "warm-editorial",
28
+ "name": "Warm Editorial & Intelligent Workspace",
29
+ "inspiration": ["Claude", "Notion", "Starbucks"],
30
+ "tokens": {
31
+ "canvas_light": "#fbfaf8",
32
+ "canvas_dark": "#1a1917",
33
+ "accent": "#cc785c",
34
+ "ink_primary": "#1e1e1d",
35
+ "ink_muted": "#6b6a67",
36
+ "hairline_border": "rgba(0, 0, 0, 0.06)",
37
+ "heading_tracking": "-0.02em",
38
+ "button_radius": "8px",
39
+ "card_radius": "12px"
40
+ },
41
+ "shadows": {
42
+ "card": "0 1px 3px rgba(0, 0, 0, 0.04), 0 4px 12px rgba(0, 0, 0, 0.03)",
43
+ "button": "0 1px 2px rgba(0, 0, 0, 0.08)"
44
+ }
45
+ },
46
+ {
47
+ "id": "electric-media",
48
+ "name": "Electric Neon & Charcoal Dark Mode",
49
+ "inspiration": ["Spotify", "PlayStation", "Replicate"],
50
+ "tokens": {
51
+ "canvas_dark": "#121212",
52
+ "surface_1": "#181818",
53
+ "surface_2": "#282828",
54
+ "accent_volt": "#1ed760",
55
+ "ink_primary": "#ffffff",
56
+ "ink_muted": "#b3b3b3",
57
+ "heading_tracking": "-0.025em",
58
+ "button_radius": "9999px",
59
+ "card_radius": "8px"
60
+ },
61
+ "shadows": {
62
+ "card": "0 8px 24px rgba(0, 0, 0, 0.5)",
63
+ "button": "0 4px 16px rgba(30, 215, 96, 0.3)"
64
+ }
65
+ },
66
+ {
67
+ "id": "precision-luxury",
68
+ "name": "Precision Luxury & Minimal Industrial",
69
+ "inspiration": ["BMW", "Apple", "Stripe"],
70
+ "tokens": {
71
+ "canvas_light": "#ffffff",
72
+ "canvas_dark": "#050505",
73
+ "surface_metal": "linear-gradient(180deg, rgba(255, 255, 255, 0.05) 0%, rgba(255, 255, 255, 0.01) 100%)",
74
+ "accent": "#0066b1",
75
+ "hairline_border": "1px solid rgba(255, 255, 255, 0.12)",
76
+ "heading_tracking": "-0.04em",
77
+ "button_radius": "4px",
78
+ "card_radius": "16px"
79
+ },
80
+ "shadows": {
81
+ "card": "0 20px 40px -15px rgba(0, 0, 0, 0.6), inset 0 1px 0 rgba(255, 255, 255, 0.1)",
82
+ "button": "inset 0 1px 0 rgba(255, 255, 255, 0.2)"
83
+ }
84
+ },
85
+ {
86
+ "id": "dense-fintech",
87
+ "name": "Dense Pro Dashboard & High-Speed Fintech",
88
+ "inspiration": ["Binance", "Coinbase", "Raycast"],
89
+ "tokens": {
90
+ "canvas_dark": "#0b0e11",
91
+ "surface_card": "#181a20",
92
+ "accent_gold": "#fcd535",
93
+ "accent_green": "#0ecb81",
94
+ "accent_red": "#f6465d",
95
+ "ink_primary": "#eaecef",
96
+ "ink_muted": "#848e9c",
97
+ "font_mono": "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas",
98
+ "heading_tracking": "-0.015em",
99
+ "button_radius": "6px",
100
+ "card_radius": "8px"
101
+ },
102
+ "shadows": {
103
+ "card": "0 2px 8px rgba(0, 0, 0, 0.3)",
104
+ "button": "none"
105
+ }
106
+ }
107
+ ]
108
+ }
@@ -0,0 +1,95 @@
1
+ # CIP Deliverable Guide
2
+
3
+ ## Core Identity
4
+
5
+ ### Primary Logo
6
+ - Vector format (SVG, AI, EPS)
7
+ - Clear space rules defined
8
+ - Scalable from favicon to billboard
9
+
10
+ ### Logo Variations
11
+ - Horizontal, vertical, stacked
12
+ - Icon/symbol only
13
+ - Monochrome versions (black, white, reversed)
14
+
15
+ ## Stationery Set
16
+
17
+ ### Business Card
18
+ - Standard: 3.5x2 inches / 85x55mm
19
+ - Premium paper stock (300-400gsm)
20
+ - Finishes: matte, spot UV, foil, emboss
21
+
22
+ ### Letterhead
23
+ - A4 or Letter size
24
+ - Header area for logo/contact
25
+ - Digital and print versions
26
+
27
+ ### Envelope
28
+ - DL, C4, C5 sizes
29
+ - Logo on flap or front
30
+ - Return address styling
31
+
32
+ ## Office Environment
33
+
34
+ ### Reception Signage
35
+ - 3D dimensional letters
36
+ - Backlit LED options
37
+ - Materials: acrylic, metal, wood
38
+
39
+ ### Wayfinding System
40
+ - Consistent icon system
41
+ - Clear hierarchy
42
+ - ADA compliance
43
+
44
+ ### Wall Graphics
45
+ - Mission/values displays
46
+ - Large-scale murals
47
+ - Window frosting
48
+
49
+ ## Apparel
50
+
51
+ ### Polo Shirt
52
+ - Embroidery preferred
53
+ - Left chest placement
54
+ - Quality fabric (pique cotton)
55
+
56
+ ### Uniforms
57
+ - Department color coding
58
+ - Name badge integration
59
+ - Safety requirements if applicable
60
+
61
+ ## Vehicle Branding
62
+
63
+ ### Car/Sedan
64
+ - Door panel branding
65
+ - Partial or full wrap
66
+ - Contact information visible
67
+
68
+ ### Fleet Vehicles
69
+ - Consistent design across fleet
70
+ - High visibility contact details
71
+ - Professional installation
72
+
73
+ ## Digital Assets
74
+
75
+ ### Social Media
76
+ - Profile pictures (icon version)
77
+ - Cover images (platform-specific)
78
+ - Post templates
79
+
80
+ ### Email Signature
81
+ - HTML responsive
82
+ - Max 600px width
83
+ - Essential contact only
84
+
85
+ ## Events & Promotional
86
+
87
+ ### Trade Show Booth
88
+ - Modular design
89
+ - Easy assembly
90
+ - Key messaging visible
91
+
92
+ ### Promotional Items
93
+ - Quality over quantity
94
+ - Useful items preferred
95
+ - Brand colors prominent
@@ -0,0 +1,121 @@
1
+ # CIP Design Reference
2
+
3
+ Corporate Identity Program design with 50+ deliverables, 20 styles, 20 industries. Generate mockups with Gemini Nano Banana (Flash/Pro).
4
+
5
+ ## Scripts
6
+
7
+ | Script | Purpose |
8
+ |--------|---------|
9
+ | `scripts/cip/search.py` | Search deliverables, styles, industries; generate CIP briefs |
10
+ | `scripts/cip/generate.py` | Generate CIP mockups with Gemini (Flash/Pro) |
11
+ | `scripts/cip/render-html.py` | Render HTML presentation from CIP mockups |
12
+ | `scripts/cip/core.py` | BM25 search engine for CIP data |
13
+
14
+ ## Commands
15
+
16
+ ### CIP Brief (Start Here)
17
+
18
+ ```bash
19
+ python3 scripts/cip/search.py "tech startup" --cip-brief -b "BrandName"
20
+ ```
21
+
22
+ ### Search Domains
23
+
24
+ ```bash
25
+ # Deliverables
26
+ python3 scripts/cip/search.py "business card letterhead" --domain deliverable
27
+
28
+ # Design styles
29
+ python3 scripts/cip/search.py "luxury premium elegant" --domain style
30
+
31
+ # Industry guidelines
32
+ python3 scripts/cip/search.py "hospitality hotel" --domain industry
33
+
34
+ # Mockup contexts
35
+ python3 scripts/cip/search.py "office reception" --domain mockup
36
+ ```
37
+
38
+ ### Generate Mockups
39
+
40
+ ```bash
41
+ # With logo (RECOMMENDED - uses image editing)
42
+ python3 scripts/cip/generate.py --brand "TopGroup" --logo /path/to/logo.png --deliverable "business card" --industry "consulting"
43
+
44
+ # Full CIP set with logo
45
+ python3 scripts/cip/generate.py --brand "TopGroup" --logo /path/to/logo.png --industry "consulting" --set
46
+
47
+ # Pro model for 4K text rendering
48
+ python3 scripts/cip/generate.py --brand "TopGroup" --logo logo.png --deliverable "business card" --model pro
49
+
50
+ # Custom deliverables with aspect ratio
51
+ python3 scripts/cip/generate.py --brand "GreenLeaf" --logo logo.png --industry "organic food" --deliverables "letterhead,packaging,vehicle" --ratio 16:9
52
+
53
+ # Without logo (AI generates interpretation)
54
+ python3 scripts/cip/generate.py --brand "TechFlow" --deliverable "business card" --no-logo-prompt
55
+ ```
56
+
57
+ ### Render HTML Presentation
58
+
59
+ ```bash
60
+ python3 scripts/cip/render-html.py --brand "TopGroup" --industry "consulting" --images /path/to/cip-output
61
+ python3 scripts/cip/render-html.py --brand "TopGroup" --industry "consulting" --images ./topgroup-cip --output presentation.html
62
+ ```
63
+
64
+ ## Models
65
+
66
+ - `flash` (default): `gemini-2.5-flash-image` - Fast, cost-effective
67
+ - `pro`: `gemini-3-pro-image-preview` - Quality, 4K text rendering
68
+
69
+ ## Deliverable Categories
70
+
71
+ | Category | Items |
72
+ |----------|-------|
73
+ | Core Identity | Logo, Logo Variations |
74
+ | Stationery | Business Card, Letterhead, Envelope, Folder, Notebook, Pen |
75
+ | Security/Access | ID Badge, Lanyard, Access Card |
76
+ | Office Environment | Reception Signage, Wayfinding, Meeting Room Signs, Wall Graphics |
77
+ | Apparel | Polo Shirt, T-Shirt, Cap, Jacket, Apron |
78
+ | Promotional | Tote Bag, Gift Box, USB Drive, Water Bottle, Mug, Umbrella |
79
+ | Vehicle | Car Sedan, Van, Truck |
80
+ | Digital | Social Media, Email Signature, PowerPoint, Document Templates |
81
+ | Product | Packaging Box, Labels, Tags, Retail Display |
82
+ | Events | Trade Show Booth, Banner Stand, Table Cover, Backdrop |
83
+
84
+ ## Design Styles
85
+
86
+ | Style | Colors | Best For |
87
+ |-------|--------|----------|
88
+ | Corporate Minimal | Navy, White, Blue | Finance, Legal, Consulting |
89
+ | Modern Tech | Purple, Cyan, Green | Tech, Startups, SaaS |
90
+ | Luxury Premium | Black, Gold, White | Fashion, Jewelry, Hotels |
91
+ | Warm Organic | Brown, Green, Cream | Food, Organic, Artisan |
92
+ | Bold Dynamic | Red, Orange, Black | Sports, Entertainment |
93
+
94
+ ## HTML Presentation Features
95
+
96
+ - Hero section with brand name, industry, style, mood
97
+ - Deliverable cards with mockup images
98
+ - Descriptions: concept, purpose, specifications
99
+ - Responsive desktop/mobile, dark theme
100
+ - Images embedded as base64 (single-file portable)
101
+
102
+ ## Workflow
103
+
104
+ 1. Generate CIP brief → `scripts/cip/search.py --cip-brief`
105
+ 2. Generate mockups with logo → `scripts/cip/generate.py --brand --logo --industry --set`
106
+ 3. Render HTML presentation → `scripts/cip/render-html.py --brand --industry --images`
107
+
108
+ **Tip:** If no logo exists, use Logo Design (built-in) to generate one first.
109
+
110
+ ## Detailed References
111
+
112
+ - `references/cip-deliverable-guide.md` - Deliverable specifications
113
+ - `references/cip-style-guide.md` - Design style descriptions
114
+ - `references/cip-prompt-engineering.md` - AI generation prompts
115
+
116
+ ## Setup
117
+
118
+ ```bash
119
+ export GEMINI_API_KEY="your-key"
120
+ pip install google-genai pillow
121
+ ```
@@ -0,0 +1,84 @@
1
+ # CIP Mockup Prompt Engineering
2
+
3
+ ## Base Prompt Structure
4
+
5
+ ```
6
+ Professional corporate identity mockup photograph showing [DELIVERABLE] for brand '[BRAND_NAME]', [STYLE] design style, using colors [COLORS], [TYPOGRAPHY] typography, logo placement: [PLACEMENT], [MATERIALS] materials with [FINISHES] finish, [CONTEXT] setting, [MOOD] mood, photorealistic product photography, soft natural lighting, high quality professional shot, 8k resolution detailed
7
+ ```
8
+
9
+ ## Deliverable-Specific Modifiers
10
+
11
+ ### Business Card
12
+ ```
13
+ business card on marble surface, stack of cards, premium paper texture, soft shadows, 45 degree angle
14
+ ```
15
+
16
+ ### Letterhead
17
+ ```
18
+ letterhead flat lay with envelope and pen, velvet fabric background, brand stationery set, overhead view
19
+ ```
20
+
21
+ ### Office Signage
22
+ ```
23
+ 3D logo signage on office wall, modern lobby interior, backlit LED, brushed metal finish, architectural photography
24
+ ```
25
+
26
+ ### Vehicle Branding
27
+ ```
28
+ branded vehicle on urban street, 3/4 front angle view, professional car wrap, motion blur background optional
29
+ ```
30
+
31
+ ### Apparel (Polo/T-Shirt)
32
+ ```
33
+ folded polo shirt on clean background, embroidered logo on chest, premium fabric texture, product photography
34
+ ```
35
+
36
+ ## Style Modifiers
37
+
38
+ ### Corporate Minimal
39
+ ```
40
+ clean minimal aesthetic, white space, subtle shadows, matte finish, professional
41
+ ```
42
+
43
+ ### Luxury Premium
44
+ ```
45
+ dark background, dramatic rim lighting, gold accents, premium materials, sophisticated
46
+ ```
47
+
48
+ ### Modern Tech
49
+ ```
50
+ gradient colors, geometric elements, clean surfaces, futuristic, innovative
51
+ ```
52
+
53
+ ### Warm Organic
54
+ ```
55
+ natural materials, kraft paper texture, warm lighting, authentic, artisan
56
+ ```
57
+
58
+ ## Lighting Modifiers
59
+
60
+ - **Studio:** `professional studio lighting, even illumination`
61
+ - **Natural:** `soft natural daylight, window light`
62
+ - **Dramatic:** `dramatic rim light, dark background, high contrast`
63
+ - **Warm:** `warm golden hour lighting, cozy atmosphere`
64
+
65
+ ## Context Modifiers
66
+
67
+ - **Marble desk:** `white marble surface, soft shadows, luxury`
68
+ - **Wooden table:** `warm wood grain, natural, artisan`
69
+ - **Office interior:** `modern office environment, architectural`
70
+ - **Flat lay:** `overhead view, organized arrangement`
71
+ - **Lifestyle:** `in-use context, human element`
72
+
73
+ ## Quality Modifiers
74
+
75
+ Always include:
76
+ ```
77
+ photorealistic, professional photography, high quality, 8k resolution, detailed, sharp focus
78
+ ```
79
+
80
+ ## Negative Prompts (what to avoid)
81
+
82
+ ```
83
+ blurry, low quality, distorted text, misspelled, amateur, clipart, cartoon, illustration, watermark
84
+ ```
@@ -0,0 +1,68 @@
1
+ # CIP Design Style Guide
2
+
3
+ ## Corporate Minimal
4
+ **Industries:** Finance, Legal, Consulting, Tech
5
+ **Colors:** Navy (#0F172A), White (#FFFFFF), Blue accents
6
+ **Typography:** Clean sans-serif (Inter, Helvetica)
7
+ **Materials:** Premium matte paper, subtle textures
8
+ **Finishes:** Matte, spot UV on logo
9
+
10
+ ## Modern Tech
11
+ **Industries:** Tech, SaaS, Startups, AI
12
+ **Colors:** Purple (#6366F1), Cyan (#0EA5E9), Green (#10B981)
13
+ **Typography:** Geometric sans (Outfit, Poppins)
14
+ **Materials:** Smooth surfaces, gradient prints
15
+ **Finishes:** Gloss, metallic accents
16
+
17
+ ## Luxury Premium
18
+ **Industries:** Fashion, Jewelry, Hotels, Fine Dining
19
+ **Colors:** Black (#1C1917), Gold (#D4AF37), White
20
+ **Typography:** Elegant serif (Playfair), thin sans
21
+ **Materials:** Heavy cotton paper, leather, metal
22
+ **Finishes:** Gold foil, emboss, deboss, soft-touch
23
+
24
+ ## Classic Traditional
25
+ **Industries:** Law Firms, Heritage Brands, Finance
26
+ **Colors:** Navy, Burgundy, Gold
27
+ **Typography:** Traditional serif (Times, Garamond)
28
+ **Materials:** Quality laid paper, wood
29
+ **Finishes:** Letterpress, gold emboss
30
+
31
+ ## Warm Organic
32
+ **Industries:** Food, Organic, Wellness, Craft
33
+ **Colors:** Brown (#8B4513), Green (#228B22), Cream
34
+ **Typography:** Friendly serif, organic script
35
+ **Materials:** Kraft paper, recycled materials
36
+ **Finishes:** Uncoated, natural textures
37
+
38
+ ## Bold Dynamic
39
+ **Industries:** Sports, Entertainment, Gaming
40
+ **Colors:** Red (#DC2626), Orange (#F97316), Black
41
+ **Typography:** Bold condensed sans
42
+ **Materials:** High-contrast, metallic
43
+ **Finishes:** Gloss, vibrant colors
44
+
45
+ ## Fresh Modern
46
+ **Industries:** Healthcare, Wellness, Fintech
47
+ **Colors:** Mint (#10B981), Sky (#0EA5E9), White
48
+ **Typography:** Modern rounded sans
49
+ **Materials:** Light, clean surfaces
50
+ **Finishes:** Matte, clean minimal
51
+
52
+ ## Soft Elegant
53
+ **Industries:** Beauty, Wedding, Spa, Fashion
54
+ **Colors:** Pink (#F472B6), Gold, White
55
+ **Typography:** Elegant script, thin sans
56
+ **Materials:** Soft-touch, quality paper
57
+ **Finishes:** Rose gold foil, emboss
58
+
59
+ ## Color Psychology
60
+
61
+ | Color | Meaning | Best Use |
62
+ |-------|---------|----------|
63
+ | Blue | Trust, stability | Finance, Tech, Healthcare |
64
+ | Green | Growth, nature | Eco, Wellness, Organic |
65
+ | Gold | Luxury, prestige | Premium, Jewelry |
66
+ | Red | Energy, passion | Food, Sports |
67
+ | Black | Sophistication | Luxury, Fashion |
68
+ | White | Clean, minimal | Tech, Healthcare |
@@ -0,0 +1,146 @@
1
+ # ME-DESIGN CLI & Linter Architecture Specification (ADR-001)
2
+
3
+ สถาปัตยกรรมเครื่องมือ Static Analysis + Browser Verification สำหรับ `medesign-cli` เพื่อการพัฒนาและเผยแพร่เป็น Open-Source บน GitHub และ npm
4
+
5
+ ---
6
+
7
+ ## 1. Dual-Tier Verification Pipeline
8
+
9
+ การตรวจคุณภาพ UI/UX ระดับวิศวกรรมต้องแยกชั้นการวิเคราะห์อย่างชัดเจน เพื่อป้องกัน False Positives จากการเดาสไตล์ที่ยังไม่ได้เรนเดอร์:
10
+
11
+ ```mermaid
12
+ flowchart TD
13
+ Source["Source Code<br/>(JSX / TSX / CSS / HTML)"] --> Static["Tier 1: Static Analysis Engine<br/>• Babel Parser (@babel/parser)<br/>• PostCSS AST (@postcss)<br/>• Tailwind Utility Extractor"]
14
+ Static --> IR["Unified Design IR<br/>(Intermediate Representation)"]
15
+ IR --> Rules["Rule Engine & Diagnostics<br/>• Semantic State Contract<br/>• Color Dependency Graph<br/>• Grid Order & Anti-AI Tells"]
16
+
17
+ Rules --> Gate{"Mode Selection"}
18
+ Gate -- "Static Only (--no-browser)" --> Scorer["Q-Score & Governance Engine"]
19
+ Gate -- "Full Audit (Playwright)" --> Browser["Tier 2: Browser Runtime Verification<br/>• Computed Styles & Real Contrast (axe-core)<br/>• Keyboard Focus Ring Visibility<br/>• Layout Bounds & CLS Measurement"]
20
+ Browser --> Scorer
21
+
22
+ Scorer --> HardGate{"Hard Invariants Pass?"}
23
+ HardGate -- "No" --> Exit1["Exit Code 1<br/>Hard Failure / Remediation Report"]
24
+ HardGate -- "Yes" --> CheckQ{"Q-Score >= 75?"}
25
+ CheckQ -- "No" --> Exit1
26
+ CheckQ -- "Yes" --> Exit0["Exit Code 0<br/>Production Release Approved"]
27
+ ```
28
+
29
+ ---
30
+
31
+ ## 2. Unified Design IR (Intermediate Representation)
32
+
33
+ ข้อมูลทุกชนิดจาก AST ต่างๆ จะถูก Normalization เข้าสู่โมเดลกลางเดียวกัน:
34
+
35
+ ```typescript
36
+ export interface DesignElement {
37
+ id: string;
38
+ source: {
39
+ file: string;
40
+ line?: number;
41
+ column?: number;
42
+ };
43
+ semanticRole?: string;
44
+ tag: string;
45
+ classNames: string[];
46
+ inlineStyles?: Record<string, string>;
47
+ expectedStates?: ('default' | 'hover' | 'pressed' | 'focus-visible' | 'disabled' | 'loading')[];
48
+ rendered?: {
49
+ bounds?: { x: number; y: number; width: number; height: number };
50
+ computedStyles?: Record<string, string>;
51
+ contrastRatio?: number;
52
+ focusVisible?: boolean;
53
+ };
54
+ }
55
+
56
+ export interface Diagnostic {
57
+ ruleId: string;
58
+ category: 'H' | 'I' | 'G' | 'R' | 'V';
59
+ severity: 'error' | 'warning' | 'info';
60
+ confidence: 'high' | 'medium' | 'low';
61
+ hardInvariant: boolean;
62
+ message: string;
63
+ file: string;
64
+ line?: number;
65
+ column?: number;
66
+ remediation?: string;
67
+ }
68
+ ```
69
+
70
+ ---
71
+
72
+ ## 3. The 5-Category Q-Score Formulation
73
+
74
+ คำนวณคะแนนรวมคุณภาพผ่านสมการถ่วงน้ำหนัก:
75
+ $$Q = 0.30H + 0.25I + 0.20G + 0.15R + 0.10V$$
76
+
77
+ - **$H$ (Hierarchy & Task Saliency - 30%):** จุดโฟกัสสอดคล้องกับ Attention Model (Task-First, Spatial, Alert-First, Reading, F, Z)
78
+ - **$I$ (Information Architecture - 25%):** ความครบถ้วนของ State Contract (6 สถานะ), แหล่งข้อมูล และการจัดกลุ่มข้อมูล
79
+ - **$G$ (Geometry & Coherence - 20%):** Concentric Border Radius, Hit Target $\ge 44\text{px}$, และ Aspect Ratio ของโมดูล
80
+ - **$R$ (Responsive Stability & CLS - 15%):** Reserved Geometry, Stable Data Regions, Breakpoint Flow (CLS $\approx 0$)
81
+ - **$V$ (Visual Craft & Anti-Slop - 10%):** การใช้ OKLCH/OKLab, Tinted Neutrals, Zero Em-Dash, Zero Decisionless Uniformity
82
+
83
+ ### Zero-Compromise Gating Policy:
84
+ 1. หากพบข้อผิดพลาดระดับ **Hard Invariant Failure** (แม้เพียงจุดเดียว) $\longrightarrow$ **Result: FAIL (Exit Code 1)** โดยไม่สนใจว่า $Q$-Score จะได้ 95+ หรือไม่
85
+ 2. เกณฑ์คะแนน:
86
+ - $90.0 - 100.0$: **PASS** (เกณฑ์ปล่อยสู่ Production)
87
+ - $75.0 - 89.9$: **REVIEW REQUIRED** (Candidate ที่ต้องตรวจสอบคำเตือน)
88
+ - $< 75.0$: **FAIL** (ปรับปรุงโครงสร้างก่อนส่งมอบ)
89
+
90
+ ---
91
+
92
+ ## 4. CLI Terminal Summary Card Specification
93
+
94
+ เมื่อรัน `npx medesign lint [path]` ระบบจะพิมพ์รายงานสรุปผลในรูปแบบ Compact Card:
95
+
96
+ ```text
97
+ ME-DESIGN vNext
98
+ Design Quality Audit
99
+ ────────────────────────────────────────
100
+
101
+ Project src/
102
+ Archetype Geospatial Situation Awareness (32)
103
+ Analysis Static AST + PostCSS
104
+ Ruleset medesign-standard@1.0.0
105
+
106
+ QUALITY SCORE
107
+ Hierarchy (H) 94.0 / 100
108
+ Information (I) 88.0 / 100
109
+ Geometry (G) 92.0 / 100
110
+ Responsive (R) 85.0 / 100
111
+ Visual Craft (V) 90.0 / 100
112
+
113
+ Q-SCORE 90.6 / 100 [PASS]
114
+
115
+ HARD INVARIANTS
116
+ PASS Dual-Theme Contrast (AAA/AA)
117
+ PASS Keyboard Focus Visibility (:focus-visible)
118
+ PASS Hit Target Isolation (>= 44px)
119
+ PASS Reduced Motion Compliance
120
+
121
+ FINDINGS
122
+ 0 hard invariant failures
123
+ 0 errors
124
+ 2 warnings
125
+
126
+ warn MD204 src/components/Table.tsx:42
127
+ Consider using Named Grid Areas instead of implicit flow.
128
+
129
+ ────────────────────────────────────────
130
+ RESULT: PASS (Exit Code: 0)
131
+ ```
132
+
133
+ ---
134
+
135
+ ## 5. Monorepo & AI Agent Integration Blueprint
136
+
137
+ ### โครงสร้างแพ็กเกจ (pnpm Monorepo):
138
+ - `packages/cli`: คำสั่ง CLI, Command Parser, Terminal Reporter (`dist/bin.js`)
139
+ - `packages/core`: Unified Design IR, Rule Contracts, Scoring Engine
140
+ - `packages/rules-standard`: กฎสากลสำหรับ Web App & Landing Page
141
+ - `packages/rules-engineering`: กฎสำหรับ GIS, CAD, Telemetry, HMI ISA-101
142
+
143
+ ### Shared Rule Registry สำหรับ AI Coding Assistants:
144
+ - **Claude Code:** `.claude/skills/medesign-audit/SKILL.md`
145
+ - **Cursor:** `.cursor/rules/medesign.mdc`
146
+ - **Antigravity:** `.agents/skills/medesign/SKILL.md`