chore: new README

README.md

@@ -6,24 +6,69 @@ Links: **[ilw-card in Builder](https://builder3.toolkit.illinois.edu/component/i
 
 ## Overview
 
-A 1-3 paragraph explanation of what the component does and how it presents.
+A card component that can be used as a container for grouping information, reminiscent of a physical
+note or playing card. 
+
+By default, the card is a white box with a dark border, limited in width, showing the content inside of it. There are
+several variations:
+
+- The top of the card can have an image using `slot="image"`, or an icon using `slot="icon"`.
+- The whole card can be made clickable using the attribute `clickable`.
+- Text content can be centered using the `centered` attribute.
+- Color themes for `gray`, `blue`, `orange`, `blue-gradient` and `orange-gradient`. For example, `theme="blue"`.
 
 ## Code Examples
 
+### Basic card with buttons
+
+```html
+<ilw-card>
+    <h3>Student Life</h3>
+    <p>Animal sciences students extend their learning and career networks beyond the classroom. </p>
+    <ul class="ilw-buttons">
+        <li><a href="#">Learn More <span class="ilw-sr-only">About Student Life</span></a></li>
+        <li><a href="#">Contact Us</a></li>
+    </ul>
+</ilw-card>
+```
+
+### Card with an image
+
 ```html
-<ilw-card></ilw-card>
+<ilw-card>
+    <img src="https://picsum.photos/500/297" alt="" slot="image">
+    <h3>Student Life</h3>
+    <p>Animal sciences students extend their learning and career networks beyond the classroom. </p>
+    <p><a href="#" class="ilw-button">Learn More <span class="ilw-sr-only">About Student Life</span></a></p>
+</ilw-card>
 ```
 
-## Accessibility Notes and Use
+### Clickable card
+
+A clickable card uses the first link found in the contents as the primary link to use for the whole
+card. When using this form, do not wrap the whole contents of the card in a link, that is done automatically.
+
+A clickable card can have additional buttons or links that function as normal. Clicking the card outside of
+those will utilize the first link in the contents.
+
+```html
+<ilw-card clickable>
+    <img src="https://picsum.photos/500/297" alt="" slot="image">
+    <h3>
+        <a href="#">Student Life</a>
+    </h3>
+    <p>Animal sciences students extend their learning and career networks beyond the classroom. </p>
+    <p><a href="#" class="ilw-button">Contact Us</a></p>
+</ilw-card>
+```
 
-Consider accessibility, both for building the component and for its use:
+## Accessibility Notes
 
-- Is there sufficient color contrast?
-- Can the component be fully understood without colors?
-- Does the component need alt text or ARIA roles?
-- Can the component be navigated with a keyboard? Is the tab order correct?
-- Are focusable elements interactive, and interactive elements focusable?
-- Are form fields, figures, fieldsets and other interactive elements labelled?
+- **Images and icons** on cards should generally be decorative with an empty `alt=""` attribute. If you do need an image
+  that needs to be described, consider placing it below the heading. If it's at the top with an alt text,
+  it may be confusing for screen readers if it comes before the title of the card.
+- **Centered text** can be harder to read, so avoid longer card text that's centered.
+- Make sure **links and buttons** are descriptive, using `ilw-sr-only` if needed to add context.
 
 ## External References