commit c5888b173f64b9497e57afdebfb020d912728f53 Author: zlei9 Date: Sun Mar 29 09:50:06 2026 +0800 Initial commit with translated description diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..ebbc254 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,180 @@ +--- +name: Image +slug: image +version: 1.0.4 +homepage: https://clawic.com/skills/image +description: "创建、检查、处理和优化图像文件。" +changelog: "Expanded the skill with branding, screenshot, accessibility, and richer platform-specific workflows while preserving stronger image-processing guidance." +metadata: {"clawdbot":{"emoji":"🖼️","os":["linux","darwin","win32"]}} +--- + +## When to Use + +Use when the main artifact is an image file or visual asset, especially when format choice, resizing, cropping, compression, metadata, transparency, color profile, responsive delivery, social specs, marketplace requirements, or print readiness matter. + +If the task is destination-specific, load the matching file before deciding: +- `web.md` for responsive delivery, LCP/CLS, `srcset`, lazy loading, SVG, and modern web formats. +- `social.md` for platform dimensions, safe zones, and feed/story/banner exports. +- `ecommerce.md` for marketplace product-image rules, white backgrounds, zoom, and catalog consistency. +- `photography.md` for RAW, ICC profiles, print export, EXIF, and non-destructive editing. +- `branding.md` for logos, icons, favicons, app icons, SVG consistency, and small-size legibility. +- `screenshots.md` for UI captures, documentation images, annotations, redaction, and marketing/device frames. +- `accessibility.md` for alt text, decorative vs informative images, text in images, charts, and contrast-aware image delivery. +- `commands.md` when the user needs concrete ImageMagick or Pillow examples. + +Keep the main workflow in this file, then pull in the specialized file for the exact delivery context instead of guessing from generic image advice. + +## Quick Reference + +| Situation | Load | Why | +|-----------|------|-----| +| Web optimization, responsive images, lazy loading, SVG | `web.md` | Avoid CLS/LCP mistakes, oversized assets, and wrong web formats | +| Color profiles, metadata, RAW, print, non-destructive workflows | `photography.md` | Protect color intent, print readiness, and master-file quality | +| Social platform dimensions, safe zones, banners, previews | `social.md` | Prevent unsafe crops, unreadable text, and uploader recompression surprises | +| Product photos, marketplace standards, catalog consistency | `ecommerce.md` | Preserve zoom detail, white-background compliance, and catalog consistency | +| Logos, favicons, SVGs, app icons, icon sets | `branding.md` | Protect small-size legibility, SVG consistency, and multi-format icon delivery | +| UI screenshots, docs captures, redaction, annotations | `screenshots.md` | Avoid blurry captures, privacy leaks, and misleading before/after comparisons | +| Alt text, text-in-image risk, charts, decorative vs informative images | `accessibility.md` | Keep image work usable and compliant, not only visually correct | +| ImageMagick and Pillow commands | `commands.md` | Use concrete commands once the export decision is already clear | + +## Fast Workflow + +1. Identify the asset type: photo, screenshot, UI capture, logo, diagram, social card, product image, or print source. +2. Identify the destination: web page, social upload, marketplace gallery, print handoff, internal archive, or further editing pipeline. +3. Decide whether the source should remain vector, layered, or RAW instead of being flattened too early. +4. Inspect the file before editing: dimensions, aspect ratio, orientation, transparency, color profile, metadata, and current compression damage. +5. Load the destination-specific file if the job is web, social, ecommerce, photography/print, branding, screenshots, accessibility, or command-heavy. +6. Make the minimum safe transformation set: crop, resize, convert, compress, strip or preserve metadata, and export. +7. Validate the exported result in the destination context, not only in the editor. + +## Asset-Type Defaults + +| Asset type | Usually best starting point | Watch out for | +|-----------|-----------------------------|---------------| +| Photo | WebP or AVIF for web, JPEG fallback, layered/RAW master for editing | Color profile shifts, overcompression, platform recompression | +| Product photo | JPEG or WebP for delivery, high-res clean master | White background, edge cleanup, zoom detail, consistency | +| Screenshot or UI capture | PNG or lossless WebP | JPEG blur, privacy leaks, unreadable text | +| Logo or simple icon | SVG master, PNG fallbacks only when needed | Tiny details, unsupported SVG pipelines, dark/light contrast | +| Social/OG card | PNG or high-quality JPEG sized for preview | Unsafe crop, tiny text, double compression | +| Diagram or chart | SVG when possible, PNG when fixed raster needed | Thin lines, low contrast, missing explanatory text | +| Print image | TIFF or high-quality JPEG with correct profile | Wrong profile, wrong physical size, no bleed | + +## Core Rules + +### 1. Choose the workflow by destination, not by habit + +- Web delivery, social export, ecommerce prep, print output, and archive preservation are different image jobs. +- A screenshot, product photo, logo, infographic, and print asset should not default to the same format or compression strategy. +- Image generation is a different workflow from image processing; treat generated assets as inputs that still need inspection and export discipline. +- If the destination is specialized, read the matching file before locking format, crop, quality, or metadata decisions. +- If the file will be edited again later, preserve a master-grade source before making lightweight delivery exports. + +### 2. Pick formats by content, not by trend + +- Photos usually want AVIF or WebP for modern web delivery, with JPEG fallback when compatibility matters. +- Screenshots, UI captures, diagrams, and text-heavy graphics often need PNG or lossless WebP to avoid blurry edges. +- Logos, icons, and simple illustrations should stay vector (`.svg`) when the target supports it. +- Transparency changes the decision: JPEG drops alpha, while PNG, WebP, and AVIF can preserve it. +- Animated GIF is rarely the best output; animated WebP, MP4, or WebM are usually smaller and cleaner. +- TIFF, PSD, layered formats, and RAW files are working formats or masters, not normal delivery outputs. +- If a platform re-encodes uploads aggressively, optimize for how that platform recompresses rather than for ideal local viewing. +- Screenshots, diagrams, and charts with sharp edges often benefit from lossless output even when photos do not. + +### 3. Preserve color, transparency, and detail deliberately + +- Web assets should usually end in sRGB unless the destination explicitly needs something else. +- Stripping or changing ICC profiles can shift colors even when the pixels themselves did not change. +- Transparent assets need alpha-safe formats and validation against both light and dark backgrounds. +- Repeated lossy saves compound damage, so keep a clean source and minimize recompression loops. +- Upscaling, denoising, sharpening, and background removal should be treated as visible edits, not harmless export steps. + +### 4. Resize, crop, and compress in the right order + +- Decide aspect ratio first, crop second, resize third, and compress last. +- Do not upscale by default; extra pixels do not create missing detail. +- Retina or HiDPI exports should be intentional, not automatic overkill. +- As a starting point, 2x is the normal Retina export and 3x should be deliberate, not default. +- Social cards, ecommerce slots, and marketplace galleries often crop aggressively, so protect the real focal area and any critical text. +- A file that fits the pixel spec can still fail if the crop cuts off faces, products, labels, or UI affordances. +- If text is embedded inside the image, validate at the smallest realistic preview size, not only at full resolution. + +### 5. Treat metadata and orientation as real delivery concerns + +- EXIF orientation can make an image look upright in one viewer and rotated in another after export. +- Public web assets usually should strip GPS and unnecessary camera metadata. +- Copyright, author, or provenance metadata may need to be preserved for editorial, legal, or archive use. +- Metadata decisions are part of the workflow, not an afterthought. +- Preserve filenames and output naming conventions when downstream systems map assets by exact names or SKU patterns. +- Do not strip metadata blindly if the workflow depends on authoring info, rights data, timestamps, or orientation. + +### 6. Use practical budgets and delivery defaults + +- For web work, use budgets as a forcing function, not as decoration. +- A useful default starting point is: hero image under 200 KB, content image under 100 KB, thumbnail under 30 KB, raster icon under 5 KB. +- Reserve layout space with explicit dimensions or aspect ratio when the image ships on the web. +- Do not lazy-load the primary hero or likely LCP image. +- A file that "looks fine locally" is not finished if it breaks CLS, LCP, or responsive delivery in the real page. +- A small file is not automatically good if detail, text legibility, product edges, or gradients collapse. +- If a platform will recompress the image anyway, leave enough headroom that the second compression does not destroy the result. + +### 7. Validate against the actual destination + +- Platform specs are not interchangeable: web hero, social preview, app store art, marketplace gallery, and print ad all have different constraints. +- Ecommerce images may need background consistency, edge cleanliness, square-safe crops, and zoom-friendly detail. +- Social images need safe composition because feeds crop previews differently across platforms. +- Print assets care about physical size, bleed, and color handling in ways web exports do not. +- If the asset ships on the web, remember the surrounding delivery too: width, height, alt text, and whether the image should carry text at all. +- If the asset will be uploaded to a third-party platform, check the post-upload result because many pipelines resize, strip profiles, flatten metadata, or recompress again. +- If the image carries meaning, validate its accessibility too: alt text strategy, text legibility, decorative vs informative role, and whether the meaning should have stayed in HTML or surrounding copy. + +### 8. Batch safely and keep the original reversible + +- Work from originals or clean masters, not from already-optimized outputs. +- Batch processing should apply consistent rules, but still spot-check representative files before touching the whole set. +- One wrong crop preset, color conversion, or lossy export can damage an entire batch quickly. +- Keep per-destination exports separated from masters so the next edit does not accidentally start from a degraded derivative. + +## Specialized Cases Worth Loading + +- Load `branding.md` when the asset is a logo, app icon, favicon, social avatar, badge, or reusable icon set. +- Load `screenshots.md` when the asset is a UI capture, bug report image, tutorial screenshot, release-note image, or device-framed marketing visual. +- Load `accessibility.md` when the image needs alt text, contains embedded text, carries chart/diagram meaning, or may be decorative instead of informative. + +## What Good Looks Like + +- The chosen format matches the content and the destination, not a blanket preference. +- The exported file keeps the right focal area, text legibility, transparency, and color intent. +- Metadata is preserved or stripped deliberately. +- The file size is efficient without obvious visual damage. +- The asset still works after the actual upload, embed, or platform preview step. +- The agent has not flattened a vector, layered, or RAW source earlier than necessary. +- The asset is still understandable in its real use context, not just visually attractive in isolation. + +## Common Traps + +- Saving transparent images as JPEG and silently losing the alpha channel. +- Using JPEG for screenshots or UI captures and turning sharp text into mush. +- Shipping a file that matches the requested dimensions but has the wrong aspect ratio or unsafe crop. +- Recompressing the same JPEG multiple times and blaming the tool instead of the workflow. +- Stripping metadata and accidentally breaking orientation, licensing context, or provenance needs. +- Forgetting sRGB and wondering why colors shift between editing tools, browsers, and marketplaces. +- Using SVG where the target platform strips it, rasterizes it badly, or blocks it entirely. +- Assuming AVIF or WebP is safe everywhere when some platforms, email clients, or upload pipelines still normalize back to JPEG or PNG. +- Embedding critical text into images where HTML or native UI text should have carried the meaning. +- Hitting the file-size budget but missing visual quality because the image was resized, cropped, or sharpened badly. +- Rasterizing a logo too early and then fighting blurry exports forever. +- Shipping a screenshot with secrets, personal data, or unstable timestamps still visible. +- Treating alt text, captions, or chart summaries as someone else's problem after the pixels look good. + +## Related Skills +Install with `clawhub install ` if user confirms: +- `image-edit` — Masking, cleanup, inpainting, and targeted visual edits. +- `image-generation` — AI image generation and editing across current model providers. +- `photography` — Capture, color, and print-oriented photo workflows. +- `svg` — Vector graphics workflows when raster files are the wrong output. +- `ecommerce` — Marketplace and product-listing requirements that often constrain image delivery. + +## Feedback + +- If useful: `clawhub star image` +- Stay updated: `clawhub sync` diff --git a/_meta.json b/_meta.json new file mode 100644 index 0000000..3986c98 --- /dev/null +++ b/_meta.json @@ -0,0 +1,6 @@ +{ + "ownerId": "kn73vp5rarc3b14rc7wjcw8f8580t5d1", + "slug": "image", + "version": "1.0.4", + "publishedAt": 1773254447006 +} \ No newline at end of file diff --git a/accessibility.md b/accessibility.md new file mode 100644 index 0000000..f04eab6 --- /dev/null +++ b/accessibility.md @@ -0,0 +1,53 @@ +# Accessibility for Images + +## Core Rule + +- An image is not finished when it only looks good; it must also be understandable and usable in context. + +## Alt Text by Role + +- Decorative image: use empty alt text (`alt=""`) so assistive tech can skip it. +- Informative image: describe the content or takeaway briefly and specifically. +- Functional image: describe the action or destination, not just the pixels. +- Complex chart or diagram: alt text alone is not enough; provide nearby summary or structured explanation too. + +## Alt Text Rules + +- Describe meaning and purpose, not every visible pixel. +- Do not start with "image of" or "picture of" unless that distinction matters. +- Keep it concise, but not so short that it loses the point. +- Captions and surrounding text can reduce what the alt text needs to repeat. +- If the surrounding copy already says the same thing, avoid redundant alt text. + +## Text Inside Images + +- If the text is important, it should usually exist in real HTML or nearby copy too. +- Social images, banners, infographics, and screenshots often hide key meaning in pixels; duplicate the important message elsewhere when the medium allows. +- Tiny text that is readable in the editor but not in a preview is an accessibility failure even if the export dimensions are technically correct. + +## Charts, Diagrams, and Data Visuals + +- Alt text should summarize the main takeaway, not list every bar or data point. +- If precise values matter, provide the values in nearby text or a data table. +- Colors alone should not carry the only distinction between categories or states. +- Thin lines, pale labels, and low-contrast legends disappear first when charts are resized. + +## Contrast and Overlays + +- Text over photos often needs a deliberate overlay, blur, or crop change to stay readable. +- White text on a bright image and dark text on a muddy background both fail fast in previews. +- Overlays should improve readability without flattening the image so much that it loses meaning. + +## Icons and UI Imagery + +- Icon-only controls still need accessible names outside the image itself. +- If an icon can be misread without a label, assume many users will misread it. +- Decorative icons do not need verbose alt text if adjacent text already carries the meaning. + +## Common Accessibility Traps + +- Writing alt text that describes appearance but misses purpose. +- Repeating the exact caption inside alt text. +- Using images to carry headings, buttons, or instructions that should be live text. +- Publishing charts with no summary of the actual insight. +- Putting critical text near image edges where crops, previews, or zoom reduce legibility. diff --git a/branding.md b/branding.md new file mode 100644 index 0000000..fa0bca4 --- /dev/null +++ b/branding.md @@ -0,0 +1,52 @@ +# Branding, Logos, Icons, and Favicons + +## Core Rule + +- Keep the source of truth in vector form when possible. +- Export PNG fallbacks from the vector source instead of editing the raster fallback and letting quality drift. +- If a logo or icon must work at 16-32 px, design for that size explicitly instead of shrinking the desktop version and hoping. + +## Logos and Marks + +- Detailed wordmarks and tiny taglines usually do not survive favicon or avatar sizes. +- Prepare simplified marks for tiny surfaces: favicon, social avatar, app icon, browser tab, and notification icon are not the same job as hero branding. +- Test logos on light and dark backgrounds before declaring the export done. +- Thin outlines, hairline strokes, and low-contrast brand colors disappear first at small sizes. + +## SVG Rules + +- Preserve the vector master when the destination supports SVG. +- Keep the SVG simple: remove hidden layers, editor cruft, and unnecessary groups. +- Use a consistent viewBox and avoid accidental off-canvas whitespace. +- For icon sets, keep stroke width, caps, joins, padding, and optical weight consistent across the set. +- If the SVG is going to be styled by CSS, prefer `currentColor` over hardcoded fills when appropriate. + +## Raster Fallbacks + +- Export PNG when transparency matters and SVG is unsupported or blocked. +- Export JPEG only when the asset is photographic or the destination forbids alpha-safe formats. +- Do not let transparent logos pick up accidental matte colors during export. +- If a logo is going onto colored backgrounds, preview that exact background before final export. + +## Favicons and App Icons + +- A real favicon package often needs more than one file: SVG, ICO, apple-touch icon, and larger app icons. +- Apple touch icons need an opaque background; transparent icons can render badly or fill with black. +- Favicon or app-icon artwork should live in the central safe area, not touch edges. +- If the mark is not readable at 16 px, simplify it instead of sharpening it harder. + +## Icon-Set Consistency + +- Do not mix filled, outlined, rounded, and sharp-corner icons randomly in one set unless that contrast is intentional. +- Similar icons should share the same baseline geometry, padding, and visual weight. +- Curves often look optically thinner than straight segments, so balance by shape size, not random stroke-width overrides. +- Review icons at 1x and 2x sizes on both light and dark surfaces. + +## Common Branding Traps + +- Exporting one logo variant and using it everywhere. +- Using a horizontal logo where a square avatar or app icon is needed. +- Leaving too much transparent padding around the mark so it looks tiny in production. +- Converting a vector icon to JPEG and losing edges, alpha, and crispness. +- Shipping an icon set where every icon has slightly different stroke thickness or corner behavior. +- Forgetting that browser tabs, mobile home screens, and social avatars all crop and display branding differently. diff --git a/commands.md b/commands.md new file mode 100644 index 0000000..80aa511 --- /dev/null +++ b/commands.md @@ -0,0 +1,144 @@ +# Image Processing Commands + +These are specific examples for cases where the user needs concrete commands rather than only decision guidance. + +## ImageMagick + +### Resize + +```bash +magick input.jpg -resize 1920x1080\> output.jpg +magick input.jpg -resize 800x600! output.jpg +``` + +### Format Conversion + +```bash +magick input.jpg -quality 80 output.webp +magick input.png -background white -flatten output.jpg +magick input.jpg -quality 75 output.avif +``` + +### Orientation and Metadata + +```bash +magick input.jpg -auto-orient output.jpg +magick input.jpg -auto-orient -strip output.jpg +identify -verbose input.jpg | grep -i exif +``` + +### SVG Optimization and Rasterization + +```bash +npx svgo input.svg -o output.svg +magick -background none -density 300 input.svg -resize 512x512 output.png +``` + +### Batch Processing + +```bash +mogrify -format webp -quality 80 *.jpg +mogrify -resize 1920x1080\> *.jpg +``` + +### Aspect-Ratio Crop + +```bash +magick input.jpg -gravity center -crop 1200x630+0+0 +repage output.jpg +magick input.jpg -resize 1200x630^ -gravity center -extent 1200x630 output.jpg +``` + +## Pillow + +### Resize + +```python +from PIL import Image + +img = Image.open("input.jpg") +img = img.resize((800, 600), Image.Resampling.LANCZOS) +img.save("output.jpg", quality=85) +``` + +### WebP Conversion + +```python +from PIL import Image + +img = Image.open("input.jpg") +img.save("output.webp", "WEBP", quality=80, method=6) +``` + +### Transparency to White Background + +```python +from PIL import Image + +img = Image.open("input.png") +if img.mode in ("RGBA", "LA", "P"): + background = Image.new("RGB", img.size, (255, 255, 255)) + background.paste(img, mask=img.split()[-1] if img.mode == "RGBA" else None) + img = background +img.save("output.jpg", quality=85) +``` + +### Thumbnail + +```python +from PIL import Image + +img = Image.open("input.jpg") +img.thumbnail((300, 300), Image.Resampling.LANCZOS) +img.save("thumb.jpg", quality=75) +``` + +## Built-in and Alternative Tools + +### macOS `sips` + +```bash +sips -Z 1600 input.jpg --out output.jpg +sips -s format webp input.png --out output.webp +``` + +- Useful when Pillow or ImageMagick are unavailable. +- Validate quality and metadata handling because `sips` is convenient, not always the most controllable. + +### Sharp (Node.js) + +```bash +npx sharp input.jpg --resize 1600 --webp quality=80 -o output.webp +npx sharp input.png --flatten background=white --jpeg quality=85 -o output.jpg +``` + +- Good for scripted web pipelines and batch conversions. +- Still inspect transparency flattening, color handling, and output dimensions deliberately. + +### `exiftool` + +```bash +exiftool input.jpg +exiftool -gps:all= -overwrite_original input.jpg +exiftool -all= -overwrite_original input.jpg +``` + +- Useful when metadata handling is the real job. +- Prefer targeted stripping when rights data or timestamps still matter. + +### `ffmpeg` for Animated Images + +```bash +ffmpeg -i input.gif -vf "fps=15,scale=1200:-1:flags=lanczos" output.webm +ffmpeg -i input.gif -vf "fps=15,scale=1200:-1:flags=lanczos" -loop 0 output.webp +``` + +- Better than treating every animation problem as a GIF problem forever. + +## Command Traps + +- Always auto-orient before final export if EXIF rotation exists. +- Flatten alpha intentionally when converting transparent images to JPEG. +- Use `LANCZOS` for final downscaling, not low-quality defaults. +- Spot-check one file before running a batch command across everything. +- Prefer writing outputs to a new path instead of overwriting the only good source. +- Treat `npx` examples as remote-code execution from the package registry and use them only in trusted environments. diff --git a/ecommerce.md b/ecommerce.md new file mode 100644 index 0000000..63590db --- /dev/null +++ b/ecommerce.md @@ -0,0 +1,60 @@ +# E-commerce Product Images + +## Resolution and Framing + +- Minimum working baseline: **1000 × 1000 px** +- Better zoom-safe default: **2000 × 2000 px** +- Main catalog images often want **1:1** +- Small products and detail shots usually need more source resolution, not more sharpening + +## Background and Edge Quality + +- Main marketplace image often needs pure white or near-pure-white background. +- Product fill commonly should sit around **85-95%** of the frame for major marketplaces. +- Edges must be clean: no halos, dirty masks, or fringing. +- If shadows are allowed, keep them subtle and consistent across the catalog. +- Keep enough padding that the product does not feel cramped after marketplace cropping or thumbnail rounding. + +## Color and Consistency + +- Use sRGB for marketplace delivery. +- Do not auto-enhance product color without validating against the real item. +- Keep crop margins, lighting direction, and white balance consistent across the set. +- Catalog inconsistency makes the whole store feel lower quality even when each image is individually acceptable. +- Variant images should preserve a consistent camera angle and scale unless the marketplace expects a different shot type. +- If background removal is used, inspect edges around hair, glass, reflective metal, and fabric fringing at 100%. + +## Marketplace Rules + +| Platform | Typical baseline | +|----------|------------------| +| Amazon | White main image, square-safe, zoom-friendly | +| Shopify | Flexible background, but consistency matters | +| Etsy | Stronger lifestyle freedom, but thumbnails still need clarity | +| Walmart | White-background expectations are stricter | + +- Marketplace uploaders normalize aggressively; validate the processed result after upload when it matters. +- Some catalogs require the main image to be cleaner and stricter than secondary lifestyle images; do not apply one styling rule to both. +- If a store theme renders product cards larger than the uploaded image can support, the fix is usually source dimensions and theme sizing together, not more sharpening alone. + +## Product-Image Traps + +- Product too small in frame +- Background not truly white where required +- Detail lost because the source was over-compressed +- Variant images cropped inconsistently +- Reflection, shadow, or mask style changing from product to product +- Text overlays or badges that are not allowed on main images +- Cutout edges that look fine zoomed out but fail at zoom or marketplace moderation +- Uploading already heavily compressed files and then letting the marketplace compress them again + +## Quality Checklist + +``` +□ Product fills the frame appropriately +□ White-background requirement checked +□ Edge cleanup verified at 100% +□ Zoom/detail still holds up +□ Catalog crop and lighting look consistent +□ Metadata/privacy decision made +``` diff --git a/photography.md b/photography.md new file mode 100644 index 0000000..763cda3 --- /dev/null +++ b/photography.md @@ -0,0 +1,70 @@ +# Photography, Color, and Print + +## Color Profiles + +| Profile | Use For | +|---------|---------| +| `sRGB` | Web delivery, most marketplaces, social | +| `Adobe RGB` | Print workflows with wider gamut | +| `ProPhoto RGB` | High-end RAW editing and master files | + +- Browsers and many upload pipelines effectively expect sRGB. +- Wide-gamut files exported for the web without conversion often look washed out or inconsistent. +- Embed the ICC profile when the destination respects color management. + +## RAW and Non-Destructive Editing + +- RAW files are source negatives; do not overwrite them. +- Keep edits in sidecars, catalogs, layered masters, or non-destructive instructions when possible. +- White balance corrections are safer in RAW than in JPEG. +- Different RAW converters can produce visibly different output from the same file. +- Keep at least one master export suitable for future edits before creating flattened delivery versions. +- Noise reduction, clarity, and sharpening should be balanced for the final destination; settings that feel dramatic on screen often print badly. + +## Metadata and EXIF + +Preserve when needed: +- Copyright and author data +- Editorial provenance +- Archive or legal context + +Strip when appropriate: +- Public web publishing +- Sensitive location data +- Irrelevant camera metadata on lightweight delivery assets + +GPS warning: +- Strip GPS before public delivery for homes, private locations, or sensitive subjects. + +## Print Export Rules + +| Setting | Web | Print | +|--------|-----|-------| +| Color space | sRGB | Adobe RGB or printer profile | +| Resolution | 72-150 PPI guidance | 300 PPI typical | +| Format | WebP/JPEG/PNG | TIFF or high-quality JPEG | +| Metadata | Minimal | Preserve if needed | + +- Print work must care about physical size, bleed, sharpening target, and final output process. +- A web export that looks good on screen is not automatically print-safe. +- Ask whether the destination printer, lab, or publication has its own profile and export requirements before assuming a generic print preset. +- Soft-proofing or at least checking for gamut clipping is worth it when brand colors or skin tones must survive print. + +## Retouching Traps + +- Over-smoothing skin or texture until the file looks synthetic. +- Aggressive sharpening halos that only become obvious in print. +- Cropping too tightly and leaving no safe room for print trims or editorial layouts. + +## Quality Control + +Before delivery: + +``` +□ Orientation fixed +□ ICC profile intentional +□ No clipped highlights or blocked shadows +□ No obvious halos or oversharpening +□ Dust spots or sensor marks checked +□ Metadata decision made on purpose +``` diff --git a/screenshots.md b/screenshots.md new file mode 100644 index 0000000..19ac121 --- /dev/null +++ b/screenshots.md @@ -0,0 +1,48 @@ +# Screenshots, UI Captures, and Documentation Images + +## Capture and Export Rules + +- Capture from the real rendered interface, not from a scaled preview inside a design tool or browser zoom guess. +- Use PNG or lossless WebP for screenshots, UI captures, terminal images, and annotated docs unless there is a strong reason not to. +- Keep a clean master before adding arrows, callouts, blurs, or frames. +- If a screenshot is evidence or documentation, do not crop away the context that proves what the user should see. + +## Redaction and Privacy + +- Check for tokens, emails, names, avatars, tabs, URLs, timestamps, and notifications before sharing. +- Blur, mask, or replace sensitive data deliberately; do not rely on tiny text being unreadable. +- Redaction must be irreversible in the exported asset, not just hidden behind a translucent layer in the editor. + +## Annotation Rules + +- Add arrows, highlights, and callouts sparingly and keep them high contrast. +- Do not let annotations cover the thing they are trying to explain. +- If multiple steps are shown, use consistent numbering and visual language across the set. +- For bug reports or release notes, the annotation should point at the defect or change without forcing the reader to hunt for it. + +## Consistency for Series and Comparisons + +- Before/after comparisons should use the same zoom, theme, device class, and crop. +- Tutorial step images should keep consistent window chrome, spacing, and annotation style. +- If one screenshot is dark mode and the next is light mode, that difference should be intentional and labeled. + +## Marketing and Device Frames + +- Keep an unframed master and export device-framed marketing variants separately. +- Device frames are for presentation, not for core source control of the screenshot. +- Reflections, shadows, and perspective mockups should not hide the actual UI. +- If the product is mobile-first, validate that tiny UI text still reads after the frame and background treatment. + +## Documentation and OCR Safety + +- Screenshots that contain code, logs, or settings should keep text readable enough for OCR and human scanning. +- Avoid aggressive compression on terminal captures and code screenshots. +- If the user needs the content to be searchable or screen-reader-friendly, duplicate the important text in surrounding copy rather than relying on the screenshot alone. + +## Common Screenshot Traps + +- Exporting screenshots as JPEG and blurring small text. +- Sharing unstable UI elements like toasts, timestamps, or notifications that make the docs age badly. +- Leaving secrets in browser tabs, URLs, or side panels. +- Comparing two UI states with different crops, zoom levels, or themes and calling it a fair comparison. +- Over-annotating until the screenshot becomes harder to parse than the original screen. diff --git a/social.md b/social.md new file mode 100644 index 0000000..7e9eaae --- /dev/null +++ b/social.md @@ -0,0 +1,50 @@ +# Social Media Image Exports + +Platform UIs change often. Use these as high-confidence working defaults, then recheck the final platform uploader when a campaign is high stakes. + +## Core Sizes + +| Platform | Format | Dimensions | Notes | +|----------|--------|------------|-------| +| Instagram feed portrait | 4:5 | 1080 × 1350 | Strong default for feed reach | +| Instagram story / reel cover | 9:16 | 1080 × 1920 | Keep key content away from edges | +| X card image | 1.91:1 | 1200 × 628 | Safer for link previews | +| LinkedIn feed square | 1:1 | 1200 × 1200 | Clean default for mixed content | +| Facebook feed image | 1.91:1 | 1200 × 630 | Common share preview shape | +| YouTube thumbnail | 16:9 | 1280 × 720 | Text must stay legible at small size | +| Pinterest pin | 2:3 | 1000 × 1500 | Standard pin ratio | +| OG / social preview card | 1.91:1 | 1200 × 630 | Safe default for link previews and embeds | + +## Safe-Zone Rules + +- Keep essential text, faces, logos, and product edges away from the outer margins. +- Story and reel formats need wider top/bottom safety because UI chrome overlays them. +- Banners and headers crop unpredictably across desktop and mobile. +- A technically correct size can still fail if the real focal point sits too close to an edge. + +## Social Export Rules + +- Use RGB and sRGB. +- Avoid tiny text that only works in the full-resolution editor view. +- Compress enough to upload fast, but not so hard that gradients, skin, or text show visible damage. +- If text matters, validate legibility on a small preview, not only at full size. +- Platform uploaders often recompress again, so leave enough quality headroom for the second pass. +- Thumbnail crops and in-feed previews may differ from the full asset view, so verify the preview state the audience actually sees. +- If the same campaign must ship to multiple platforms, export per platform rather than trusting one master crop to survive everywhere. + +## Content Guidance + +- Put the main subject, offer, or headline in the central safe area. +- Do not rely on corner badges, tiny logos, or edge-aligned text surviving previews. +- Faces, products, and callouts need more breathing room in stories, reels, and banners than in square feed posts. +- The real first impression is often the tiny preview tile, not the full-screen asset; optimize for that moment too. + +## Quick Checks + +``` +□ Correct aspect ratio +□ Key content centered within a safe area +□ Text readable on mobile +□ No edge-cropped logos or faces +□ Exported in RGB/sRGB +``` diff --git a/web.md b/web.md new file mode 100644 index 0000000..300c10a --- /dev/null +++ b/web.md @@ -0,0 +1,106 @@ +# Web Image Optimization + +## Responsive Images + +Standard `srcset` widths: **320w, 640w, 768w, 1024w, 1366w, 1600w, 1920w** + +```html + +``` + +- Do not generate every possible size; match real CSS breakpoints. +- Four or five sizes is usually enough for one asset. +- Width descriptors are safer than DPR-only guesswork when layouts vary. +- If art direction changes by viewport, use `` or separate crops, not one crop forced everywhere. +- Do not force a single desktop crop into mobile if the subject or text loses meaning; mobile often needs a different crop, not just fewer pixels. + +## LCP, Lazy Loading, and Fetch Priority + +Use `loading="lazy"` for: +- Below-the-fold images +- Galleries and long lists + +Do not lazy-load: +- Hero or likely LCP images +- First visible product or content images +- Critical background replacements that define the first viewport + +Useful defaults: +- LCP image: `loading="eager"` and consider `fetchpriority="high"` +- Non-critical images: `loading="lazy"` + +## Aspect Ratio and CLS + +Always reserve space: + +```html + +``` + +Or: + +```css +.container { aspect-ratio: 16 / 9; } +``` + +Common ratios: + +| Ratio | Use | +|------|-----| +| 16:9 | Hero banners, video covers | +| 4:3 | Traditional photos | +| 3:2 | DSLR photos | +| 1:1 | Products, avatars, social | +| 21:9 | Wide banners | + +- Never ship web images without reserved space if layout stability matters. + +## Format Rules for Web + +- AVIF first when the stack and audience can handle it. +- WebP is the pragmatic default for most modern photo delivery. +- PNG stays useful for UI, screenshots, diagrams, and alpha-safe assets. +- JPEG is still a fallback, not a failure, when compatibility wins. +- SVG is ideal for icons and simple illustrations but must be validated against the target pipeline. +- OG and social-preview images are a special case: PNG or high-quality JPEG often survive platform ingest more predictably than aggressively compressed modern formats. +- Meaningful content images should not be hidden only in CSS backgrounds when semantic HTML image delivery would be more accessible and controllable. + +## SVG and Text-in-Image Rules + +- Run SVGs through SVGO. +- Keep `viewBox`; remove hardcoded `width` and `height` when CSS should control size. +- Inline very small critical SVGs; externalize bigger or reusable ones. +- Avoid embedding essential copy inside raster images when HTML text should carry meaning. +- If the SVG comes from design tools, inspect it for hidden raster layers, giant embedded paths, or exported cruft before shipping it. + +## CMS and Pipeline Reality + +- Many CMSs and site builders resize, rename, or recompress uploads after you hand them off. +- If the destination pipeline creates its own responsive derivatives, start from a clean master instead of pre-baking every size blindly. +- A web upload that looks sharp in the media library can still be rendered too large in the layout and become blurry. + +## Delivery Traps + +- Shipping one oversized source and trusting CSS to resize it. +- Using one crop for every breakpoint even when the composition breaks on narrow screens. +- Choosing AVIF for everything even when fallback or encoding time makes the workflow worse. +- Forgetting that email builders, CMS pipelines, and some older browsers may still flatten the format decision back to JPEG or PNG. + +## Performance Checklist + +``` +□ LCP image not lazy-loaded +□ Width/height or aspect-ratio reserved +□ Modern format chosen intentionally +□ srcset/sizes only for real breakpoints +□ No oversized originals shipped to the browser +□ Alt text present when the image conveys meaning +```