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 |
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
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”)
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
- 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 |