Skip to content

Commit 2f22655

Browse files
author
Developer
committed
Add fork customization tools and contribution guidelines
Fork-friendly enhancements for public release: - Add FORK_INSTRUCTIONS.md: manual and automated fork setup guide, upstream sync instructions, test validation steps - Add .github/CONTRIBUTING.md: detailed contribution process covering example format requirements, checklist item format, standards mapping guidance, PR template, code of conduct (clinical tone, non-clinical boundaries, person-first language), and review process - Add scripts/customize-fork.sh: interactive bash script that detects GNU vs BSD sed, scans for files containing original references, applies replacements with per-file change counts, prints git diff stats and next-step instructions; handles empty input validation and user confirmation before making changes - Update README.md: add 'For Fork Maintainers' section after installation instructions; replace contributing section with structured table of contribution types and link to CONTRIBUTING.md Makes the skill immediately forkable and customizable by any organization or individual contributor.
1 parent ccd565e commit 2f22655

4 files changed

Lines changed: 695 additions & 19 deletions

File tree

.github/CONTRIBUTING.md

Lines changed: 306 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,306 @@
1+
# Contributing to Depression-Sensitive Web Content Support (DS-WCS)
2+
3+
Thank you for your interest in improving cognitive accessibility and emotional safety on the web. This document explains how to contribute effectively to this OpenCode skill.
4+
5+
---
6+
7+
## Ways to Contribute
8+
9+
### 1. Report Missing Content Patterns
10+
11+
Found a problematic UX pattern not covered by the existing checklist or examples?
12+
13+
[**Open an issue**](https://github.com/simonplmak-cloud/depression-sensitive-web-content/issues/new) and include:
14+
15+
- **Pattern description:** What content or interaction creates barriers?
16+
- **Context:** Where does this appear? (error messages, CTAs, empty states, etc.)
17+
- **Impact:** How does it affect users with depression or cognitive differences?
18+
- **Proposed remediation:** How should it be rewritten?
19+
20+
**Example issue:**
21+
22+
```
23+
Title: Missing pattern: countdown timers on checkout pages
24+
25+
Pattern: Visible countdown timer ("You have 8:32 remaining") on checkout forms
26+
Context: E-commerce checkout flows
27+
Impact: Creates urgency pressure that compounds executive function difficulties;
28+
users may make rushed, incorrect decisions or abandon the task entirely
29+
Proposed remediation: Remove the timer, or extend to 15+ minutes with a
30+
non-alarming indicator (e.g. "Your cart is saved for 24 hours")
31+
```
32+
33+
---
34+
35+
### 2. Add Before/After Rewrite Examples
36+
37+
Contribute new examples to Section A.2 of the implementation guide.
38+
39+
**File:** `.opencode/skills/depression-sensitive-web-content/resources/implementation-guide.md`
40+
41+
**Where to add:** After the last numbered example in Section A.2.
42+
43+
**Required format:**
44+
45+
```markdown
46+
**Example N: [Descriptive Title] - [Platform Type] ([General Web / Sensitive Context])**
47+
48+
*Original:*
49+
```
50+
[exact problematic content]
51+
```
52+
53+
*Recommended Rewrite:*
54+
```
55+
[improved content]
56+
```
57+
58+
*Rationale:*
59+
- [Specific change 1 and why it improves accessibility]
60+
- [Specific change 2 and how it reduces cognitive load]
61+
- [Specific change 3 and how it supports emotional safety]
62+
63+
*Standards Mapping:*
64+
- WCAG 2.2: [criterion number and name, e.g. 3.3.3 Error Suggestion (AA)]
65+
- W3C COGA: [objective number and name, e.g. Objective 2: Help users avoid mistakes]
66+
- ISO 9241-110: [principle name, e.g. Error tolerance]
67+
- ISO/IEC 30071-1: [clause if applicable, e.g. Clause 8.2]
68+
```
69+
70+
**Content requirements:**
71+
72+
- Maintain a mix of general web and sensitive-context examples (healthcare, finance, job applications, wellness platforms)
73+
- Map each example to **all four standards** (WCAG 2.2, W3C COGA, ISO 9241-110, ISO/IEC 30071-1)
74+
- Use clinical and professional tone; avoid casual or colloquial language
75+
- Ensure the rationale is grounded in cognitive science or established accessibility principles
76+
77+
---
78+
79+
### 3. Expand the Audit Checklist
80+
81+
Add new checklist items to Section C of the implementation guide.
82+
83+
**File:** `.opencode/skills/depression-sensitive-web-content/resources/implementation-guide.md`
84+
85+
**Where to add:** Under the most relevant existing category (C.1–C.13), or create a new `### C.N` category if the pattern does not fit existing ones.
86+
87+
**Required format:**
88+
89+
```markdown
90+
#### C.N.M [Item Name]
91+
92+
**Check:** [One-sentence description of what to look for during an audit]
93+
94+
**Severity:** HIGH | MEDIUM | LOW
95+
96+
**Examples:**
97+
- [Concrete example of the problematic pattern]
98+
- [Another concrete example]
99+
- [A third example]
100+
101+
**Remediation:**
102+
[Clear, specific guidance on how to fix the issue]
103+
104+
**Standards References:**
105+
- WCAG [criterion number and name]
106+
- COGA Objective [number]
107+
- ISO 9241-110 ([principle name])
108+
- ISO/IEC 30071-1 (Clause [number]) — include only if directly applicable
109+
```
110+
111+
**Severity definitions:**
112+
113+
| Severity | Criteria |
114+
|----------|----------|
115+
| **HIGH** | Directly causes task abandonment, emotional distress, or prevents task completion; violates WCAG Level A |
116+
| **MEDIUM** | Increases cognitive load or emotional friction; may cause abandonment; violates WCAG Level AA or ISO 9241-110 principles |
117+
| **LOW** | Reduces comfort or satisfaction; missed improvement opportunity; does not violate standards |
118+
119+
---
120+
121+
### 4. Improve Standards Traceability
122+
123+
Help ensure that every recommendation maps accurately and completely to all four standards.
124+
125+
**Standards used in this skill:**
126+
127+
| Standard | Full Name | Primary Use |
128+
|----------|-----------|-------------|
129+
| WCAG 2.2 | Web Content Accessibility Guidelines 2.2 | Success criteria for perceivable, operable, understandable content |
130+
| W3C COGA | Cognitive and Learning Disabilities Accessibility Supplemental Guidance | Objectives for users with cognitive differences |
131+
| ISO 9241-110 | Ergonomics of Human-System Interaction: Dialogue Principles | Seven principles for effective human-system dialogue |
132+
| ISO/IEC 30071-1 | Information Technology - User Interface Accessibility | Governance, policy, and process requirements |
133+
134+
**When reviewing or improving standards mappings:**
135+
136+
- Verify WCAG success criteria numbers and conformance levels (A, AA, AAA)
137+
- Reference specific COGA objectives by number (1–4) and pattern where possible
138+
- Use ISO 9241-110 principle names consistently: Self-descriptiveness, Controllability, Conformity with user expectations, Suitability for the task, Error tolerance, Suitability for individualization, Suitability for learning
139+
- Reference ISO/IEC 30071-1 clauses (7.x, 8.x, 9.x) only where directly applicable
140+
141+
**Reference sources:**
142+
143+
- [WCAG 2.2 Quick Reference](https://www.w3.org/WAI/WCAG22/quickref/)
144+
- [W3C COGA Supplemental Guidance](https://w3c.github.io/coga/content-usable/)
145+
- [ISO 9241-110 Overview](https://www.iso.org/standard/38009.html)
146+
147+
---
148+
149+
### 5. Improve Documentation
150+
151+
Help make the skill easier to discover, understand, and use.
152+
153+
**Areas that welcome improvement:**
154+
155+
- **README.md:** Additional usage examples, installation troubleshooting, FAQ section
156+
- **SKILL.md:** Workflow clarity, edge case handling, integration examples
157+
- **FORK_INSTRUCTIONS.md:** Platform-specific customization notes
158+
- **Implementation guide:** Improved section introductions, cross-references between sections
159+
160+
---
161+
162+
## Pull Request Process
163+
164+
### Before You Start
165+
166+
1. **Fork the repository** to your own GitHub account
167+
2. **Clone your fork** locally:
168+
```bash
169+
git clone https://github.com/YOUR-USERNAME/depression-sensitive-web-content.git
170+
cd depression-sensitive-web-content
171+
```
172+
3. **Create a feature branch** with a descriptive name:
173+
```bash
174+
git checkout -b feature/add-mobile-form-examples
175+
# or
176+
git checkout -b fix/standards-mapping-c3-5
177+
```
178+
179+
### Making Changes
180+
181+
Follow the formats described above. When ready:
182+
183+
```bash
184+
git add .
185+
git commit -m "Add 2 mobile form validation examples
186+
187+
- Example 16: Mobile inline validation with haptic feedback context
188+
- Example 17: Mobile password strength indicator
189+
190+
Both examples include full WCAG 2.2, COGA, ISO 9241-110 mappings."
191+
```
192+
193+
### Testing Locally
194+
195+
Before submitting, verify the skill works in OpenCode:
196+
197+
```bash
198+
# Copy to your global skills directory
199+
cp -r . ~/.config/opencode/skills/depression-sensitive-web-content
200+
201+
# Open a project in OpenCode and test
202+
# Ask: "Audit this content for depression-sensitive issues"
203+
# Confirm the skill loads and applies your new content
204+
```
205+
206+
### Submitting the Pull Request
207+
208+
1. Push your branch to your fork:
209+
```bash
210+
git push origin feature/add-mobile-form-examples
211+
```
212+
2. Go to your fork on GitHub and click **Compare & pull request**
213+
3. Use this description template:
214+
215+
```markdown
216+
## Summary
217+
218+
[1–3 sentences describing what this PR adds or fixes]
219+
220+
## Changes
221+
222+
- [Specific change 1]
223+
- [Specific change 2]
224+
225+
## Standards Coverage
226+
227+
- [ ] All new content maps to WCAG 2.2 (verified criterion numbers)
228+
- [ ] All new content maps to W3C COGA (verified objective numbers)
229+
- [ ] All new content maps to ISO 9241-110 (verified principle names)
230+
- [ ] ISO/IEC 30071-1 referenced where directly applicable
231+
232+
## Testing
233+
234+
- [ ] Skill loads in OpenCode without errors
235+
- [ ] New examples/checklist items follow the required format
236+
- [ ] Tone is clinical/professional throughout
237+
- [ ] No medical advice or diagnosis language present
238+
```
239+
240+
---
241+
242+
## Code of Conduct
243+
244+
This project addresses mental health, cognitive differences, and emotional safety in web interfaces. All contributions must adhere to the following standards.
245+
246+
### Required
247+
248+
**Maintain clinical and professional tone**
249+
- Use evidence-based language
250+
- Cite specific standards or research where applicable
251+
- Avoid colloquialisms, casual phrasing, and informal register
252+
253+
**Include non-clinical disclaimers where appropriate**
254+
- Be explicit that this is a UX and content tool, not a clinical resource
255+
- Direct users to qualified healthcare professionals for mental health concerns
256+
257+
**Avoid medical advice or diagnosis**
258+
- Do not suggest clinical interventions for users with depression
259+
- Do not diagnose conditions based on content patterns
260+
- Focus entirely on interface and content design
261+
262+
**Use person-first, non-stigmatizing language**
263+
- Use "users with depression" rather than "depressed users"
264+
- Use "cognitive differences" in preference to value-laden alternatives
265+
- Frame all guidance as supportive, not remedial
266+
267+
**Respect diverse user needs**
268+
- Consider international and cross-cultural contexts
269+
- Avoid culturally specific assumptions in examples
270+
- Support multiple assistive technologies where relevant
271+
272+
### Not Permitted
273+
274+
- Medical advice or clinical guidance of any kind
275+
- Stigmatizing language about mental health conditions
276+
- Content lacking evidence-based or standards-aligned rationale
277+
- Examples that reproduce harmful UI patterns without clear remediation
278+
279+
Contributions that do not meet these standards will be declined with specific, constructive feedback.
280+
281+
---
282+
283+
## Review Process
284+
285+
1. **Format check:** Maintainer verifies the contribution follows the required format
286+
2. **Standards accuracy:** Criterion numbers, objective references, and principle names are verified
287+
3. **Tone review:** Contribution is checked for clinical/professional tone and non-clinical compliance
288+
4. **Feedback:** Specific, actionable feedback is provided within 7 days
289+
5. **Approval:** Approved PRs are merged and contributors are credited in the release notes
290+
291+
---
292+
293+
## Questions
294+
295+
**Not sure whether your contribution fits?**
296+
Open a [discussion issue](https://github.com/simonplmak-cloud/depression-sensitive-web-content/issues/new) before writing code. Prefix the title with `[Discussion]`, describe your idea, and ask for feedback. This saves time for everyone.
297+
298+
**Need help with standards mapping?**
299+
Open your PR as a draft and leave a comment asking specifically which standards apply to your addition. The maintainers will provide guidance before you finalize the work.
300+
301+
**Technical issues with OpenCode skill development?**
302+
See the [OpenCode documentation](https://opencode.ai/docs) for skill structure and YAML frontmatter requirements.
303+
304+
---
305+
306+
Thank you for contributing to more inclusive, emotionally safe digital experiences. Every improvement helps reduce cognitive and emotional barriers for users around the world.

0 commit comments

Comments
 (0)