design-concept-implementation

name

design-concept-implementation

description

Use when implementing an EPDC Blueprint project from a visual design concept, especially references under blueprints/dentist/concepts/. This skill teaches Codex to extract visual language, section rhythm, spacing, typography, CTA placement, and responsive intent from a concept artifact while preserving the Factory architecture, Astro implementation target, Blueprint component hierarchy, and project-owned src/data content model.

Design Concept Implementation

Overview

Use this skill to translate approved visual direction into a Factory-compliant Astro implementation. Design Specifications provide the primary AI-readable design intent; React concepts remain secondary human visual references. The Blueprint remains the source of truth for implementation structure.

Core Boundary

Separate responsibilities before changing files:

• Blueprint owns component hierarchy, layouts, rendering, route composition, data flow, and reusable contracts.
• Design Specification owns the canonical AI-readable visual hierarchy, spacing, typography, composition, CTA placement, visual rhythm, and design language.
• React Concept owns the human-approved visual artifact and should be consulted only when the Design Specification is missing or ambiguous.
• Project data owns all business content through src/data/.

Do not convert React into Astro. Implement the visual system described by the Design Specification through the active Blueprint architecture.

Required Context

Load the minimum relevant context before implementation.

Load only the files required for the selected design profile.

Do not inspect the entire blueprints/dentist/concepts/ directory unless no design profile has been specified.

• AGENTS.md
• .agents/skills/astro/SKILL.md
• docs/skills-architecture.md
• blueprints/dentist/README.md
• blueprints/dentist/patterns/page-composition.md
• blueprints/dentist/patterns/data-flow.md
• the relevant Design Specification under blueprints/dentist/concepts/specs/
• the relevant React concept files under blueprints/dentist/concepts/ only when the Design Specification needs clarification
• the generated or target project src/data/ modules

For the current Dental Blueprint concept set, load blueprints/dentist/concepts/specs/family.yaml first when designProfile: family is selected. Inspect blueprints/dentist/concepts/ as a secondary visual reference only.

Workflow

1. Load the selected Design Specification before implementing. Treat its section order, spacing scale, typography, color palette, image treatment, card style, CTA hierarchy, trust-signal placement, review placement, and responsive behavior as implementation requirements.
2. Consult the React concept only when the Design Specification is missing, ambiguous, or internally inconsistent.
3. Ignore React architecture. Do not assess hooks, component boundaries, state management, dependency choices, Tailwind usage, or shadcn/ui composition unless genuine interaction requirements are relevant.
4. Inventory reusable UI patterns from the Design Specification. Capture patterns such as hero variants, trust strips, service grids, doctor cards, testimonial formats, FAQ treatments, contact bands, sticky CTAs, and form placement.
5. Map each visual section to the nearest Blueprint component. Prefer existing blueprints/dentist/components/ and page templates before adding or changing components.
6. Map visible content to project data. Clinic identity, navigation, services, doctors, testimonials, locations, FAQs, blog entries, footer content, legal text, and SEO data must come from src/data/.
7. Implement in Astro using semantic HTML, CSS, and static rendering first. Preserve Blueprint props and typed data contracts.
8. Add client-side JavaScript only when the user-facing behavior truly requires it. Keep static content and presentational variation server-rendered.
9. Validate that the output preserves the selected Design Specification's visual intent without copying framework-specific code.

Mapping Model

Use this interpretation chain:

Design Specification

↓

Blueprint Components

↓

Project Data

↓

Astro Implementation

Secondary reference:

React Concept

Use this only for visual clarification when the Design Specification is insufficient.

Examples:

• A design specification's premium dark hero maps to the Blueprint Hero and layout styles, with actual clinic headlines and CTAs supplied by src/data/hero.ts.
• A design specification's compact conversion form maps to an Astro contact or appointment section using project-owned form labels and service options.
• A design specification's editorial blog emphasis maps to BlogGrid and project-owned blog data, not hardcoded article objects from the concept.
• A design specification's trust strip maps to TrustLogos, GoogleReviews, or a small Blueprint-compatible trust section fed from project data.

React Guidelines

React inside the Concepts folder exists only as a visual reference.

Design Specifications under blueprints/dentist/concepts/specs/ are the preferred AI-consumable source. They reduce token use, remove framework noise, and make fidelity requirements deterministic.

Production projects should default to:

• Astro
• semantic HTML
• CSS
• static rendering

Use React only when genuine client-side interactivity is required, such as:

• advanced search
• dynamic filters
• maps
• calculators
• booking widgets
• complex client state

Never use React simply because the visual reference was built in React. Do not copy React components, hooks, local arrays, Tailwind class strings, or shadcn/ui implementation details into production code.

Implementation Rules

• Preserve the Dental Blueprint as the production architecture.
• Use the selected Design Specification as the primary visual contract.
• Treat blueprints/dentist/concepts/ as a design artifact, not production code.
• Use Blueprint components instead of copying concept components.
• Keep all business content in project-level src/data/ modules.
• Keep CSS and design tokens in the generated project's style layer unless the Blueprint itself needs a reusable, generic extension.
• Prefer additive visual variants over rewriting the Blueprint's data flow.
• Preserve accessibility: semantic landmarks, ordered headings, focus states, descriptive alt text, and usable forms.
• Report any visual intent that cannot be represented by existing Blueprint contracts before expanding shared component APIs.

Validation

Before finishing, verify:

• React concept source files under blueprints/dentist/concepts/ remain untouched unless the task explicitly requires concept maintenance.
• The selected Design Specification was loaded before React concept files.
• blueprints/dentist/ remains the implementation source of truth unless the task explicitly required a Blueprint extension.
• No React code was copied into Astro files.
• Astro remains the default implementation target.
• React is recommended only for real interactivity.
• Business content is read from src/data/, not concept-local constants.
• The delivered result preserves the selected Design Specification's visual hierarchy, spacing, typography, CTA strategy, and visual rhythm.