Prerequisites
Before ingesting patterns, you’ll need Golden Pages—fully-authored reference pages that contain all the patterns for each template type. See the Golden Pages Guide for details on creating effective reference pages.Overview
Design Patterns are the building blocks Gradial uses to create and update your pages. Each pattern represents a reusable component layout from your AEM environment—things like hero banners, card grids, content blocks, and navigation elements. By ingesting patterns from your existing pages, you teach Gradial’s AI agent exactly how your components work, enabling it to accurately build new pages and update existing ones.Understanding Design Systems
A Design System in Gradial is a collection of patterns organized by page type or template. Think of it as a toolkit specific to each type of page you create.Why Organize by Page Type?
Different page types have different needs:| Page Type | Typical Patterns |
|---|---|
| Homepage | Hero carousel, featured content grid, announcement banner |
| Blog Article | Article hero, body content, author bio, related posts |
| Product Detail | Product hero, features grid, specifications, reviews |
| Landing Page | Campaign hero, benefit blocks, testimonials, CTA sections |
Collections
Collections let you organize patterns into focused, purpose-built subsets of a Design System. Rather than exposing the full pattern library for every task, Collections allow you to group patterns by use case—such as blog pages, marketing campaigns, or product flows. Key capabilities:- A pattern can belong to multiple Collections simultaneously
- Access Collections from the Collections tab on the Design System page
- Create, manage, and update Collections by adding or removing patterns
- Reuse Collections across different tasks and workspaces
Workspace Scoping
Design Systems and Collections can be scoped to specific workspaces, so each team only sees the patterns relevant to their work.- Associate a Design System with one or more workspaces
- Scope access to particular Collections within a system
- Design systems auto-filter based on the AEM integration URL of each workspace
Design System Best Practices
- Create separate Design Systems for each unique page template in your environment
- Include all available patterns for that page type—this gives the agent the full toolkit
- Use descriptive names that reflect both the pattern type and its context
- Use Collections to create focused subsets for specific use cases or teams
Ingesting Patterns
Follow these steps to add patterns to your Design System.Step 1: Create a Design System
Navigate to the Design Patterns section in your organization settings and click + Create. Enter a name and optional description for your new Design System. Choose a name that clearly identifies the page type, such as “Blog Article Patterns” or “Product Page Components.”Step 2: Add Patterns from a Golden Page
Click + Add Patterns within your Design System. You’ll need a Golden Page URL—this is the reference page you created that contains all the patterns for this template type. The URL should be a fully-formed path to your AEM author environment. Example URL format:
Note: The system automatically appends ?wcmmode=default to put AEM pages in Preview mode during analysis.
Step 3: Name Your Patterns
After detection, you’ll see a list of all patterns found on the page. Rename each pattern with a unique, descriptive name. Important: Do not accept default pattern names. Each pattern should have a unique name, even if similar layouts appear across different Design Systems. Good naming examples:Blog Article Hero(not just “Hero”)Product Feature Card Grid(not just “Card Grid”)Homepage Announcement Banner(not just “Banner”)
Step 4: Save and Review
Once all patterns are named appropriately, save your Design System. Review the pattern list to ensure everything was captured correctly.Testing Your Patterns
Before using patterns in production, verify they work correctly.Create a Test Task
Set up a test task in a development workspace with a prompt like:What to Look For
- Patterns render with correct visual structure
- Content populates in the expected fields
- Component hierarchy matches your reference page
- No missing or malformed elements
If Patterns Don’t Render Correctly
Pattern issues typically stem from field classification problems. See the Field Classification section below, or contact Gradial support for assistance with pattern refinement.Field Classification
When patterns are ingested, Gradial captures all attributes associated with each component—both visible content fields and hidden structural properties.How Classification Works
Each field is automatically classified as:| Classification | Meaning | Examples |
|---|---|---|
| High (H) | Editable content the author controls | Headlines, body text, image paths, metadata |
| Low (L) | Structural/constant values | Component type, layout identifiers |
When to Adjust Classification
You may need to manually adjust field classifications if:- Expected content fields aren’t being updated
- Structural fields are being incorrectly modified
- Metadata or hidden fields need to be author-editable
Classification Guidelines
- Set to High (H): All visible content elements, plus any hidden fields authors should control (metadata, SEO fields, etc.)
- Set to Low (L): Component type identifiers, structural constants, system-generated values
Note: Field classification is an advanced feature. Contact Gradial support if you’re unsure how to proceed with classification adjustments.
General Rules & Tips
Pattern Naming
- Every pattern needs a unique name across your entire organization
- Include the page type or context in the name
- Be specific:
Product Card GridandBlog Card Gridare better than two patterns both namedCard Grid
Environment Considerations
- Patterns are specific to each environment (Stage, Production, etc.)
- If you move from Stage to Production, you’ll need to re-ingest patterns in the new environment
Pattern Selection
When creating or updating pages, you can either:- Select specific patterns in the task configuration
- Reference the Design System by name in your prompt (e.g., “Use the Blog Article Patterns”)
- Select a Collection to use a focused, pre-grouped subset of patterns
Pattern Inheritance
When working with batch tasks, campaigns, or folders, patterns selected at the parent level automatically flow down to child tasks.- Patterns are inherited by manually created, CSV-uploaded, or agent-generated child tasks
- Pattern selections are saved to task history
- Children capture the parent’s selections at creation time—existing children are not retroactively updated
Draft Patterns
Patterns can be set to Draft status to hide them from the authoring agent while you work on them.| Status | Behavior |
|---|---|
| Released (default) | Available to the authoring agent for task execution |
| Draft | Visible in admin/design system settings only; hidden from the agent |
Maintaining Your Design System
- Add new patterns when new components are developed
- Update patterns if component structures change
- Remove deprecated patterns that are no longer in use
- Use Draft status to stage patterns before making them available to the agent
- Test after changes to verify patterns still work correctly
Troubleshooting
| Issue | Likely Cause | Solution |
|---|---|---|
| Pattern not detected | Page not in preview mode | Verify URL is correct and accessible |
| Wrong content in fields | Field classification incorrect | Review and adjust H/L classifications |
| Missing visual elements | Pattern incomplete | Re-ingest from a more complete reference page |
| Duplicate pattern names | Non-unique naming | Rename patterns with specific, contextual names |
| Pattern works in Stage but not Prod | Environment mismatch | Re-ingest patterns in Production environment |