Skip to content

Commit e429e69

Browse files
balzssclaude
balzss
and
claude
committed
docs(many): add Claude Code configuration and documentation
Add comprehensive AI assistant support: - CLAUDE.md with repository structure, workflows, and conventions - .claudeignore to optimize Claude Code performance - .gitignore entries for AI tool artifacts - Updated ai-features.md to reference CLAUDE.md - inst-ai.config.mjs for inst-ai integration 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent 8450778 commit e429e69

File tree

10 files changed

+503
-0
lines changed

10 files changed

+503
-0
lines changed

‎.claudeignore‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Dependencies
2+
node_modules/
3+
4+
# Build outputs
5+
coverage/
6+
__build__/
7+
.tmp/
8+
packages/*/lib/
9+
packages/__docs__/__build__/
10+
11+
# Git
12+
.git/
13+
14+
# Logs and build info
15+
*.log
16+
*.tsbuildinfo
17+
lerna-debug.log
18+
npm-debug.log
19+
20+
# Test artifacts
21+
regression-test/node_modules/
22+
packages/*/node_modules/
23+
24+
# Images and binary files
25+
*.png
26+
*.jpg
27+
*.jpeg
28+
*.gif
29+
*.svg
30+
*.woff
31+
*.woff2
32+
*.ttf
33+
*.eot
34+
full_logo.png
35+
logo.png
36+
37+
# Large changelog
38+
CHANGELOG.md
39+
40+
# Editor and system files
41+
.vscode/
42+
.idea/
43+
.DS_Store

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,12 @@ __build__
1717
tsconfig.build.tsbuildinfo
1818

1919
.pnp.*
20+
21+
# AI/LLM tool artifacts (Copilot & Claude)
22+
.copilot/
23+
.inst-ai/sessions
24+
25+
# Claude Code specific
26+
.claude/settings.local.json
27+
.claude/cache/
28+
.claude/*.local.*

‎.inst-ai/templates/jira/README.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Jira Templates
2+
3+
This directory contains prompt templates for generating Jira tickets from Slack conversations.
4+
5+
## Template Types
6+
7+
### Bug Report Templates
8+
- `bug-report.extraction.md` - Extracts structured data from bug report conversations
9+
- `bug-report.generation.md` - Generates final Jira ticket content for bugs
10+
11+
### Feature Request Templates
12+
- `feature-request.extraction.md` - Extracts structured data from feature request conversations
13+
- `feature-request.generation.md` - Generates final Jira ticket content for features
14+
15+
## Template Variables
16+
17+
Templates use `{{VARIABLE_NAME}}` syntax for variable substitution:
18+
19+
- `{{CONVERSATION_CONTENT}}` - The full Slack conversation text
20+
- `{{EXTRACTED_DATA}}` - JSON-formatted extracted data from the conversation
21+
22+
## Customizing Templates
23+
24+
You can override default templates by configuring custom template paths in your `inst-ai.config.js`:
25+
26+
```javascript
27+
export const config = {
28+
jira: {
29+
customTemplates: {
30+
bugReport: {
31+
extraction: './my-templates/custom-bug-extraction.md',
32+
generation: './my-templates/custom-bug-generation.md'
33+
},
34+
featureRequest: {
35+
extraction: './my-templates/custom-feature-extraction.md',
36+
generation: './my-templates/custom-feature-generation.md'
37+
}
38+
}
39+
}
40+
}
41+
```
42+
43+
## Template Format
44+
45+
Templates should be valid Markdown files with embedded prompts for the AI model. The AI will process the template content and generate responses in the expected format (JSON for extraction, ADF JSON for generation).

‎.inst-ai/templates/jira/bug-report.extraction.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Bug Report Extraction Template
2+
3+
**Task:** Analyze the conversation and extract entities into a JSON object. Use `null` for missing values.
4+
5+
**Entities:**
6+
- `component_name`: string | null - The name of the UI component or module mentioned
7+
- `browser_name`: string | null - Browser where the issue occurs (e.g., "Chrome", "Firefox", "Safari")
8+
- `os_name`: string | null - Operating system where the issue occurs (e.g., "macOS", "Windows", "Linux")
9+
- `instui_version`: string | null - InstUI version (e.g., "8.51.0", "v8.51.0"). Look for @instructure/ui-* package versions in package.json, version mentions in conversation, or CodeSandbox dependencies
10+
- `summary_of_bug`: string - Brief description of the bug
11+
- `reporter_name`: string - Name of the person reporting the bug
12+
- `environment_text`: string | null - Additional environment details
13+
- `steps_to_reproduce`: array | null - List of steps to reproduce the issue
14+
- `expected_behavior`: string | null - What should happen
15+
- `actual_behavior`: string | null - What actually happens
16+
- `workaround`: string | null - Any workarounds mentioned
17+
18+
**Conversation:**
19+
{{CONVERSATION_CONTENT}}
20+
21+
**JSON Output:**

‎.inst-ai/templates/jira/bug-report.generation.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Bug Report Generation Template
2+
3+
**Persona:** Expert Technical Writer creating a developer-ready bug report for Jira.
4+
5+
**Task:** Use the `CONTEXT` to generate a JSON object with a `summary` and an ADF `description`.
6+
7+
**Requirements:**
8+
- The `summary` must be: `Fix: [<Component Name>] <Brief problem description>`. Use the component_name from extracted data if available, otherwise use a generic name based on the affected area.
9+
- The `description` must be a valid Atlassian Document Format (ADF) JSON object.
10+
- Include all relevant technical details from the context.
11+
- Structure the description with clear sections: Problem, Environment, Steps, Expected/Actual behavior.
12+
- If component_paths are available, create an "Affected Components" section:
13+
- Add a heading (type: "heading", attrs: {level: 3}) with text "Component Paths:"
14+
- Follow immediately with paragraph(s) containing ONLY the file paths, one per paragraph
15+
- Example: If paths are ["packages/ui-button/src/index.tsx"], create a paragraph with just that text
16+
- Do NOT add bullets, lists, or code blocks - just plain paragraph text with the paths
17+
- Always include a "Context Links" section with:
18+
- Slack thread URL (if slack_thread_url is available) as a clickable link
19+
- CodeSandbox URLs (if codesandbox_urls are available) as clickable links
20+
- End with a disclaimer paragraph in italics: "This ticket was automatically generated with AI assistance from conversation data. Please review and update as needed."
21+
22+
**CONTEXT:**
23+
{{EXTRACTED_DATA}}
24+
25+
**Your Turn (Use the CONTEXT provided above):**
26+
**IMPORTANT:** Return ONLY valid JSON. Every property must be followed by a comma except the last one in an object or array. Double-check all commas before responding.
27+
**Output JSON:**

‎.inst-ai/templates/jira/feature-request.extraction.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Feature Request Extraction Template
2+
3+
**Task:** Analyze the conversation and extract entities into a JSON object. Use `null` for missing values.
4+
5+
**Entities:**
6+
- `feature_name`: string | null - The name of the requested feature
7+
- `requestor_name`: string - Name of the person requesting the feature
8+
- `business_justification`: string | null - Why this feature is needed
9+
- `proposed_solution`: string | null - How the feature should work
10+
- `affected_components`: array | null - Components that would be affected
11+
- `priority_level`: string | null - Urgency or priority mentioned
12+
- `success_criteria`: string | null - How to measure success
13+
- `alternative_solutions`: array | null - Other approaches considered
14+
15+
**Conversation:**
16+
{{CONVERSATION_CONTENT}}
17+
18+
**JSON Output:**

‎.inst-ai/templates/jira/feature-request.generation.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Feature Request Generation Template
2+
3+
**Persona:** Product Manager creating a comprehensive feature request for Jira.
4+
5+
**Task:** Use the `CONTEXT` to generate a JSON object with a `summary` and an ADF `description`.
6+
7+
**Requirements:**
8+
- The `summary` must be: `Feature: [<Component/Area Name>] <Brief description>`. Use the feature_name or affected_components from extracted data if available, otherwise use a generic name based on the affected area.
9+
- The `description` must be a valid Atlassian Document Format (ADF) JSON object.
10+
- Include business justification, proposed solution, and success criteria.
11+
- Structure the description with clear sections: Overview, Business Case, Requirements, Acceptance Criteria.
12+
- If component_paths are available, create an "Affected Components" section:
13+
- Add a heading (type: "heading", attrs: {level: 3}) with text "Component Paths:"
14+
- Follow immediately with paragraph(s) containing ONLY the file paths, one per paragraph
15+
- Example: If paths are ["packages/ui-button/src/index.tsx"], create a paragraph with just that text
16+
- Do NOT add bullets, lists, or code blocks - just plain paragraph text with the paths
17+
- Always include a "Context Links" section with:
18+
- Slack thread URL (if slack_thread_url is available) as a clickable link
19+
- CodeSandbox URLs (if codesandbox_urls are available) as clickable links
20+
- End with a disclaimer paragraph in italics: "This ticket was automatically generated with AI assistance from conversation data. Please review and update as needed."
21+
22+
**CONTEXT:**
23+
{{EXTRACTED_DATA}}
24+
25+
**Your Turn (Use the CONTEXT provided above):**
26+
**IMPORTANT:** Return ONLY valid JSON. Every property must be followed by a comma except the last one in an object or array. Double-check all commas before responding.
27+
**Output JSON:**

‎CLAUDE.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# Instructure UI - Claude Code Documentation
2+
3+
## Project Overview
4+
5+
InstUI is a React component library and design system. **Lerna 8 monorepo** with 100+ packages.
6+
7+
**Key Resources:**
8+
- Website: https://instructure.design
9+
- AI docs: https://instructure.design/llms.txt
10+
- Component docs: https://instructure.design/markdowns/[ComponentName].md
11+
- Example: https://instructure.design/markdowns/Alert.md
12+
- Example: https://instructure.design/markdowns/Button.md
13+
14+
**Tech Stack:** Node.js >=22, npm, React 18.3.1+, TypeScript 5.8.3, Emotion (CSS-in-JS), Vitest, Cypress, Chromatic
15+
16+
## Repository Structure
17+
18+
```
19+
/packages # 100+ packages
20+
/ui-* # Component packages (ui-button, ui-select, etc.)
21+
/canvas-theme # Theme packages
22+
/__docs__ # Documentation app
23+
/docs # Documentation source files
24+
/regression-test # Visual & a11y testing (Next.js 15 app)
25+
/cypress # Component tests
26+
/scripts # Build scripts
27+
```
28+
29+
**Important file locations:**
30+
- Component source: `/packages/ui-*/src/`
31+
- Component tests: Co-located with components
32+
- Theme types: `/packages/shared-types/src/ComponentThemeVariables.ts`
33+
- Visual/a11y tests: `/regression-test/`
34+
- Testing docs: `/docs/testing/testing-overview.md`
35+
36+
## Quick Start
37+
38+
```bash
39+
npm run bootstrap # First time setup (clean, build icons, compile, generate tokens)
40+
npm run dev # Start dev server at http://localhost:9090
41+
```
42+
43+
Most changes hot-reload automatically when dev server is running.
44+
45+
## Essential Commands
46+
47+
```bash
48+
# Development
49+
npm run dev # Dev server (http://localhost:9090)
50+
npm run build:types # Build TypeScript declarations
51+
52+
# Testing
53+
npm run test:vitest # Unit tests
54+
npm run cy:component # Cypress component tests
55+
56+
# Linting
57+
npm run lint:fix # Auto-fix linting issues
58+
npm run ts:check # TypeScript references check
59+
60+
# Troubleshooting
61+
npm run clean && npm run bootstrap # Fix build issues
62+
npm run clean-node && npm install # Nuclear option (removes all node_modules)
63+
```
64+
65+
## Code Style
66+
67+
**IMPORTANT: Always use functional components with React hooks for new code.**
68+
69+
- ✅ Functional components with hooks (useState, useEffect, etc.)
70+
- ❌ No class components for new code (legacy codebase has them)
71+
- ❌ **Never hardcode text** - all user-facing text must come from props (for i18n)
72+
- ✅ Support accessibility (WCAG 2.1 AA), RTL languages
73+
- ✅ Use TypeScript for all new code
74+
- ✅ Use Emotion for styling (CSS-in-JS)
75+
76+
## Finding Component Information
77+
78+
**To find available components and their packages:**
79+
- Check `/packages/__docs__/src/components.ts` - lists all components with their package locations
80+
81+
**Each component has two READMEs:**
82+
83+
1. **Component README**: `/packages/[package]/src/[Component]/README.md` ⭐
84+
- Usage examples and guidelines
85+
- **Check this first** - it has the detailed information
86+
87+
2. **Package README**: `/packages/[package]/README.md`
88+
- Package overview, installation, exports
89+
90+
**For complete API details:**
91+
- Props: Check `props.ts` files in component source
92+
- Theme variables: Check `theme.ts` files in component source
93+
94+
## Component Development Workflow
95+
96+
1. Find component in `/packages/ui-[name]/src/[Component]/`
97+
2. Check Component README for API details
98+
3. Make changes (functional components only)
99+
4. Run tests: `npm run test:vitest`
100+
5. Update both README files if needed
101+
6. Use `/commit` to create commit
102+
103+
## Breaking Changes
104+
105+
**IMPORTANT: Avoid breaking changes unless explicitly requested by the user.**
106+
107+
A change is **breaking** if it requires consumers to modify their code:
108+
109+
**Breaking changes (avoid):**
110+
- ❌ Removing or renaming a prop
111+
- ❌ Changing a prop's type or behavior
112+
- ❌ Removing or renaming a component
113+
- ❌ Changing default values that affect behavior
114+
- ❌ Removing or renaming theme variables
115+
- ❌ Removing exported utilities or functions
116+
117+
**Not breaking changes (preferred):**
118+
- ✅ Adding new optional props
119+
- ✅ Adding new components
120+
- ✅ Bug fixes that restore intended behavior
121+
- ✅ Internal refactoring without API changes
122+
- ✅ Adding new theme variables
123+
- ✅ Deprecating features with warnings (without removing)
124+
- ✅ Documentation updates
125+
126+
When a breaking change is explicitly requested, document it clearly in the commit message with `BREAKING CHANGE:` in the body.
127+
128+
## Testing Requirements
129+
130+
All components **MUST**:
131+
1. Have unit tests (Vitest + React Testing Library in `*.test.tsx`)
132+
2. Have visual regression tests in `/regression-test`
133+
3. Pass accessibility audits (WCAG 2.1 AA)
134+
4. Support RTL languages
135+
136+
### Running Tests
137+
138+
```bash
139+
npm run test:vitest # Unit tests
140+
npm run cy:component # Cypress tests
141+
142+
# Visual regression tests (in regression-test directory)
143+
cd regression-test
144+
npm run dev # Start at localhost:3000
145+
npm run cypress-chrome # Run with GUI
146+
```
147+
148+
### Adding Visual Regression Test
149+
150+
1. Create test page: `/regression-test/src/app/[component-name]/page.tsx`
151+
2. Add Cypress test: `/regression-test/cypress/e2e/spec.cy.ts`
152+
153+
See `/regression-test/README.md` for detailed instructions.
154+
155+
## Writing Documentation
156+
157+
InstUI uses custom markdown with special code blocks for interactive examples.
158+
159+
**Code block types:**
160+
- `type: code` - Syntax highlighting only
161+
- `type: embed` - Rendered component only
162+
- `type: example` - Interactive (rendered + editable) ⭐ Most common
163+
164+
**IMPORTANT:**
165+
- Always write functional component examples with hooks
166+
- All InstUI components are available without imports in examples
167+
168+
See `/docs/contributor-docs/writing-docs.md` for complete guidelines and syntax.
169+
170+
## Naming Conventions
171+
172+
- **Packages**: `ui-[component-name]` (kebab-case)
173+
- **Components**: PascalCase (Button, Select)
174+
- **Props**: camelCase with prefixes (onClick, isDisabled)
175+
- **Theme variables**: camelCase
176+
177+
## Committing & PRs
178+
179+
Use `/commit` and `/pr` slash commands - they follow InstUI conventions automatically.
180+
181+
**Branch naming:** Create feature branches from `master`
182+
183+
**PR merging:** PRs are typically squashed when merged

0 commit comments

Comments
 (0)