Component Studio

Component Studio is a project-aware AI workspace that turns a Figma design, Figma JSON export, or screenshot into a Sitecore JSS implementation.

It can generate the React component, GraphQL artifact when required, Sitecore templates, rendering definition, serialization files, and optional demo content. Unlike a generic code generator, it first analyzes the target solution and uses that evidence as part of the generation and validation contract.

Community project: This repository is not affiliated with, maintained by, or endorsed by Sitecore. Sitecore is a trademark of Sitecore Corporation A/S.

Repository: github.com/amustafa91/component-studio

At a glance

Capability	What Component Studio does
Design understanding	Inspects Figma nodes, parses supported Figma JSON structures, or uses a vision model to classify screenshots and identify visible fields and repeated content
Project awareness	Indexes existing JSS components, Tailwind tokens, breakpoints, GraphQL examples, Sitecore templates, and serialization anchors
Selectable output	Generates Frontend + Sitecore, Frontend only, or Sitecore only
Content modeling	Separates static fields, authored collections, dynamic listings, and integrated-query components
AI providers	Uses local Ollama or a remote OpenAI-compatible Chat Completions / Anthropic Messages endpoint
Guardrails	Normalizes safe variations, validates the complete response, requests focused repairs, preflights destinations, and refuses to overwrite existing target files
Sitecore delivery	Writes SCS/Unicorn-style YAML or TDS item serialization, including optional demo datasource and child items

Project status

This is an experimental developer tool. Generated code, GraphQL, Sitecore templates, serialization, and content must be reviewed and tested before production use.

The application is designed to reject invalid output before writing files, but it is not a replacement for project-specific architecture review, frontend testing, Sitecore validation, security review, or source control.

Why this project exists

Turning a design into a Sitecore component is more than a JSX exercise. A useful implementation must satisfy several contracts at the same time:

• The visual structure and responsive intent of the design.
• Sitecore JSS field types and editable rendering patterns.
• The target project's React, TypeScript, GraphQL, and Tailwind conventions.
• Sitecore template, rendering, datasource, and serialization conventions.
• Safe file placement without overwriting existing components.

Language models are good at proposing an implementation, but they do not automatically know the structure of the target solution. Component Studio surrounds the model with project analysis, structured generation, normalization, validation, collision checks, and deterministic serialization helpers.

What it generates

Output	Artifacts
Frontend	Typed Sitecore JSS React component and optional GraphQL query
Sitecore	Component template, optional repeated-item template, template sections and fields, rendering definition, and datasource configuration
Serialization	Files matching the analyzed project's supported YAML or item serialization examples
Demo content	Optional datasource and referenced child items with authorable sample values

The output scope can be selected for each run:

• Both generates frontend and Sitecore artifacts.
• Frontend only generates React and optional GraphQL without requiring Sitecore serialization anchors.
• Sitecore only generates templates, rendering items, serialization, and optional content without requiring a frontend root.

Supported design inputs

• Figma file or node URL using a Figma API token. The inspector can expose selectable component nodes and component variants.
• Manual Figma JSON import with deterministic parsing for supported structures, without a Figma API request.
• Hybrid Figma JSON + screenshot so JSON supplies exact structure and values while vision helps classify visual intent.
• Screenshot analyzed by the configured vision model.

The vision step creates a structured design description. It identifies the component type, layout, repeated structures, visible fields, responsive intent, and suggested data-access pattern before code generation begins.

When a Figma file exposes multiple components, selected nodes are generated in separate runs. A detected variant set is passed to generation as one component with variant context rather than being presented as unrelated components.

How the pipeline works

flowchart LR
    A[Design input] --> B[Design inspection]
    C[Frontend and Sitecore roots] --> D[Project analysis]
    B --> E[Generation contract]
    D --> E
    E --> F[Local or remote AI]
    F --> G[Normalize response]
    G --> H[Validate complete output]
    H --> I[Preflight paths and collisions]
    I --> J[Write selected artifacts]

Loading

1. Inspect the design

The application parses deterministic Figma structures directly when possible. Screenshot input is sent to the selected vision provider and converted into a JSON design description.

2. Analyze the target solution

Project analysis can inspect the frontend root, Sitecore serialization root, or both. Depending on the supplied paths, it discovers:

• Existing React and Sitecore JSS components.
• TypeScript and component conventions.
• Tailwind color families and responsive breakpoints.
• GraphQL examples and query style.
• Serialized templates, template fields, rendering roots, and content roots.
• Serialization format and representative anchor items.
• A suitable existing component to use as generation context.

The project name is detected from the analyzed solution; it is not a product default and is never hard-coded into Component Studio.

Analysis accepts either root independently. Frontend-only work needs a valid JSS frontend root; Sitecore output needs an existing serialization tree with exact template and rendering anchors. Demo content additionally needs an analyzed content root. The optional Sitecore URL is only used for a reachability check—it is not used as a content-authoring API.

3. Build the generation contract

The design description and relevant project evidence are combined into a structured request. Static components, authored collections, dynamic listings, and integrated GraphQL components receive different requirements.

4. Generate with a selected provider

The application supports local Ollama models and hosted providers. Model output is treated as a proposal, not as trusted files.

5. Normalize and validate

Unambiguous model variations are normalized locally. Semantic validation then checks the entire response. A focused repair attempt may be sent to the model with the exact schema or validation errors.

6. Preflight and write

The application resolves target directories, serialization anchors, and file names before writing. Existing target files are treated as conflicts and are not overwritten. Files are written only after the complete generated response passes schema and semantic validation.

Component data patterns

Component Studio distinguishes between several common Sitecore patterns:

Static authored component

Visible values become explicit Sitecore fields. The React component renders those fields directly and does not invent an item array or GraphQL query.

Authored repeatable collection

Timelines, steps, testimonials, accordions, and authored card collections can use a project-appropriate Multilist or Treelist field plus a repeated item template. The React component maps the referenced items without introducing GraphQL when the content is explicitly authored.

Dynamic listing

Search results, paginated listings, filtered results, and other query-driven designs require a GraphQL artifact and typed result mapping. Vision fields must be represented consistently in the query, React contract, and rendering.

Integrated GraphQL component

Designs classified as latest/recent content use an integrated query attached to the Sitecore rendering. The React component consumes the resulting rendering/Layout Service data and must not add an Apollo useQuery call.

Validation and safeguards

The generation contract validates more than JSON syntax. Current checks include:

• Safe component and file names.
• Allowed Sitecore field types.
• Field parity between the design, template, and React component.
• Repeated-item template and collection-reference consistency.
• GraphQL requirement and field coverage for dynamic designs.
• Sitecore JSS imports and editable field rendering.
• Analyzed Tailwind color-family usage when project tokens are available.
• Rejection of unsupported Bootstrap, Gatsby, placeholder, and raw editable HTML patterns.
• Demo datasource and item shape validation.
• Serialization GUID format and stable deterministic IDs.
• Required template, rendering, and content anchors.
• Destination preflight and existing-file collision detection.

If a local or remote model cannot produce a valid response after the allowed repair attempts, generation fails and no generated response files are written.

The allowed field types are Single-Line Text, Multi-Line Text, Rich Text, General Link, Image, Checkbox, Date, Datetime, Treelist, and Multilist. The content validator also checks safe link formats, Sitecore date formats, relationship handling, and verified media references.

Agent activity

The portal streams concise, verified execution events such as:

• Reading the design.
• Loading project context.
• Planning the selected output scope.
• Generating the structured response.
• Normalizing and validating.
• Building Sitecore serialization.
• Writing files and completing the run.

The activity panel does not display private chain-of-thought, raw model responses, raw prompts, API keys, or access tokens.

Requirements

• Node.js 18 or newer.
• npm.
• A Sitecore JSS Next.js solution, a Sitecore serialization tree, or both.
• Ollama for local generation, or access to a supported hosted model endpoint.
• A Figma token only when reading directly from the Figma API.
• A GitHub token only when scanning private organization repositories.

Quick start

git clone https://github.com/amustafa91/component-studio.git
cd component-studio
npm install
npm run dev

Open http://localhost:3000.

For a production build:

npm run build
npm start

npm start requires a successful production build first.

Local Ollama setup

The current portal defaults come from pages/index.tsx:

Setting	Default
Ollama URL	http://localhost:11434
Coding model	qwen3-coder:30b
Vision model	qwen3-vl:4b

Install and start Ollama, then pull the models you intend to use:

ollama pull qwen3-coder:30b
ollama pull qwen3-vl:4b

Model names are editable in the portal. Other Ollama models can be tried without changing application code, but model size alone does not guarantee valid output; every response must pass the same contract.

The included Modelfile contains general Sitecore generation guidance and currently derives from qwen2.5-coder:7b. It is an optional starting point for creating a custom model and is separate from the portal's qwen3-coder:30b default.

Remote AI setup

Select Remote AI in the AI connection section and provide:

• Provider protocol.
• Complete HTTPS API endpoint.
• API key.
• Coding model ID.
• Optional vision model ID.

Supported protocols:

• OpenAI-compatible Chat Completions for providers and gateways exposing that API shape.
• Anthropic Messages for Anthropic-compatible endpoints.

OpenAI-compatible providers are attempted with strict JSON Schema first. If the provider reports that response formats or grammar are unsupported, the client retries with compatible JSON modes. Every response still passes the same local schema and semantic validation.

The portal starts with the OpenAI Chat Completions URL as a convenience, but it does not select a remote model or provide credentials. For another provider, enter that provider's complete Chat Completions endpoint and model ID. Anthropic mode changes the default endpoint to /v1/messages. Remote endpoints must use HTTPS; use Local Ollama for localhost models.

Remote API keys are used for the current local request. They are not written to project context, generated files, organization profiles, or activity logs.

Typical workflow

1. Choose the intended output scope and enter the matching frontend root, Sitecore serialization root, or both.
2. Click Analyze project and review the detected context.
3. Select Figma, Figma JSON, hybrid JSON + screenshot, or Screenshot input.
4. Inspect the design and confirm the detected fields and component pattern.
5. Select Both, Frontend only, or Sitecore only.
6. Enable demo content when Sitecore output is selected and sample content is useful.
7. Add focused custom instructions when the design needs additional behavior.
8. Generate and review Agent activity.
9. Review every created file in source control before integrating it.
10. Validate and push Sitecore serialization using the target solution's normal Sitecore CLI workflow.

Use Refresh after changing the target project, Tailwind configuration, GraphQL conventions, or serialization roots. An analysis cache is keyed by the frontend and serialization paths, but stale project evidence should not be used for a new convention set.

Demo content

Demo content is available for Both and Sitecore-only runs. It can create:

• A component datasource.
• Authorable datasource field values.
• Referenced child items for repeatable collections.
• Result items for dynamic/listing demo scenarios when a result template is generated.
• Link, text, date, checkbox, and relationship values matching the generated schema.

Image fields remain empty unless project analysis provides a verified existing Sitecore media item. Creating media items and uploading media blobs are intentionally outside the current content writer.

Optional GitHub organization scan

The organization scan is an optional way to reuse patterns from mature Sitecore JSS repositories.

It:

• Accepts a GitHub organization name or organization URL.
• Ranks visible repositories using Sitecore, JSS, Next.js, React, and TypeScript signals.
• Selects a bounded set of likely component files.
• Verifies that examples import or use Sitecore JSS APIs.
• Collects nearby GraphQL or serialization companions when available.
• Stores a bounded organization profile under .cache/github_profiles.
• Optionally creates a derived Ollama model when Ollama is installed.

The scan is deliberately bounded: it inspects at most 40 ranked repositories, stores at most eight verified Sitecore JSS component examples, and caps the reusable knowledge prompt at 72,000 characters. A repository contributes no more than two component examples. The cached profile can be injected into either local or remote generation; analyzed target-project conventions and the current design remain authoritative when evidence conflicts.

Without a token, the scan can only access public repositories and receives lower GitHub API limits. A token is required for private repositories and must be authorized for the organization. The token is sent only in GitHub API request headers and is not logged, saved to the profile, or passed to an Ollama command.

Organization profiles may contain source excerpts from repositories visible to the supplied token. The entire .cache directory is ignored by Git and must remain private unless the source owners have explicitly authorized redistribution.

Serialization support

The analyzer detects SCS/Unicorn-style .yml trees and TDS .item trees from representative items in the supplied directory. The writer uses real parent IDs, root paths, template IDs, field examples, and the detected file extension rather than inventing anchors.

Generated templates include a real Template Section and individual Template Field child items. Rendering items include the component name, datasource template and location, caching settings, and an integrated query when that pattern is selected. Repeated authored collections and dynamic result types receive a separate item template. Identifiers are deterministic for the same Sitecore path.

Sitecore output will stop before any write when the analyzed template or rendering root cannot be resolved. Demo content has the same requirement for a content root. A shared Generated Content folder is reused only when its ID and path match the deterministic values expected for the analyzed root.

Before pushing generated SCS YAML, validate a target directory with:

npm run validate:scs -- "C:\path\to\serialization\FeatureTemplates\Project\Component"

This command is read-only. It parses YAML files and rejects invalid ID, Parent, and Template GUID metadata, including braced GUIDs where plain values are required.

Test and regression commands

Command	Purpose
npm run dev	Start the development server
npm run build	Type-check, lint, and create a production build
npm run evaluate	Build and run the deterministic regression suite
npm run validate:scs -- <path>	Validate generated SCS YAML metadata

The evaluation suite currently covers:

• Deterministic design parsing.
• Static, collection, listing, and integrated generation contracts.
• Demo content and referenced-item normalization.
• Agent progress events.
• Remote-provider configuration and fallback modes.
• SCS GUID formatting.
• Canonical template section and field serialization.
• Project-analysis template indexing.
• GitHub organization-scan safety and discovery rules.

Repository structure

pages/index.tsx                         Portal UI and workflow controls
pages/api/component-studio/analyze.ts  Frontend and Sitecore project analysis
pages/api/component-studio/vision.ts   Screenshot design analysis
pages/api/component-studio/run.ts      Generation, validation, preflight, and writing
pages/api/component-studio/github-scan.ts
                                        Optional organization convention scan
lib/component-studio/generation-contract.ts
                                        Response schema, normalization, and validation
lib/component-studio/project-analysis.ts
                                        Project-context types and helpers
lib/component-studio/sitecore-template-serialization.ts
                                        Canonical template serialization helpers
lib/component-studio/scs-format.ts     SCS detection and GUID validation
lib/component-studio/remote-ai.ts      Hosted-provider request adapters
lib/component-studio/progress.ts       Agent progress store
scripts/                               Deterministic regression and validation tools

Data and security considerations

• Work on a source-control branch or disposable worktree.
• Review the selected output paths before generation.
• Generated files are written to paths supplied through the local portal.
• Existing target files are treated as collisions and are not overwritten.
• Remote API keys and GitHub tokens are not persisted by the application.
• Project analysis, Figma responses/imports, and organization profiles are cached locally under .cache.
• Cached project evidence can contain source excerpts, paths, and serialization samples; .cache is excluded from Git and should be deleted before sharing a workspace archive.
• Do not scan repositories or generate derived models unless you have permission to use their source code for that purpose.

The portal's Demo privacy control masks known project values in its own inputs, summaries, and activity display. It is a presentation aid, not a data-sanitization or recording-security boundary: it does not rename source files, redact another browser/devtool window, or remove values already present in local caches.

Troubleshooting

Could not find a production build in the '.next' directory

npm start serves a production build. Run npm run build first, or use npm run dev during development. Development output is intentionally stored under .next-dev, while production output uses .next.

Screenshot analysis reports Failed to fetch

Confirm that Ollama is running at the URL shown in the portal and that the selected vision model has been pulled. For Remote AI, verify the complete HTTPS endpoint, API key, model ID, and that the chosen model accepts image input. Keep screenshots below the API's approximately 7.5 MB binary limit.

A provider reports failed to parse grammar or rejects response_format

Component Studio retries known structured-output compatibility errors with a less strict JSON mode. If all attempts fail, use a provider/model with reliable JSON output or switch to another protocol. The local schema and semantic checks are never bypassed.

Generation ends with No valid ... generation was produced

Read the validation issues in Agent activity. Common causes are missing design fields, unsupported field types, GraphQL/result-field mismatch, project-incompatible Tailwind colors or breakpoints, raw editable HTML, or malformed demo content. Refresh project analysis after convention changes and prefer focused custom instructions over a large, conflicting prompt.

Sitecore output says serialization anchors are missing

Point Sitecore serialization root at an existing tree containing the project's template and rendering root items, then run Analyze project again. Demo content also needs an existing content root. Component Studio intentionally does not invent these parent IDs.

dotnet sitecore ser push rejects a generated YAML GUID

Run npm run validate:scs -- "C:\path\to\generated\serialization". SCS metadata values for ID, Parent, and Template must be plain GUIDs, not braced GUIDs. The validation command is for YAML; TDS .item output uses its own braced format.

Generation stops because target files already exist

This is intentional. Rename the requested component, move/remove only the intended generated artifacts, or choose a clean branch/worktree. Component Studio does not overwrite existing target files.

Known limitations

• Visual similarity still requires browser review across the target project's breakpoints.
• Component Studio does not currently launch the generated component in the target application, perform browser screenshots, or run automated visual-diff testing.
• Model quality, latency, memory usage, and JSON reliability vary significantly.
• Project analysis requires representative files and anchors; an empty solution provides less useful context.
• The generator does not upload media blobs or create arbitrary Sitecore media-library items.
• The optional Sitecore URL check only tests reachability; generation writes local serialization rather than creating CMS items through a Sitecore API.
• The writer does not replace project-specific code review, serialization validation, Sitecore CLI checks, or CMS testing.
• Provider fallback modes improve compatibility but do not guarantee that every hosted model can produce a valid component.

Contributing

Issues and pull requests should describe the target Sitecore/JSS pattern, expected generated artifacts, and validation behavior. Include a deterministic fixture or regression check whenever possible.

Before submitting a change:

npm run evaluate

Do not commit .cache, local logs, API credentials, generated organization models, or source excerpts from private repositories.

License

No open-source license has been selected yet. Add a license before accepting external contributions or granting reuse rights beyond GitHub's default repository terms.