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