KCard Technical Specification

[MisRob]

Summary

KCard provides an accessible base card component. Furthermore, it offers the most frequently used card content and thumbnail layouts, as well as other customization options.

It is not meant to be the final card displayed in the Learning Equality Products. Rather, it offers a logic that is common to all of them and makes creation of final card components easier, faster, and consistent. The Products are expected to build their many card components, such as lesson card, resource card, and channel card, by importing and configuring KCard, and providing product specific logic to its slots. For illustration, here are some Kolibri cards that will be built on top of KCard:

Example 1	Example 2	Example 3	Example 4	Example 5

Here for example, KCard will provide the #footer slot and positions it. In the Kolibri codebase, we will then implement ResourceCard.vue, LessonCard.vue, etc. Each of them will use KCard and provide its #footer slot with its own logic such as progress bar, context menu, leave it empty, etc.

Available layouts for card content and thumbnails

• These are the main layouts that KCard will support (labels containing # correspond to slots, layout and thumbnailDisplay are props)

• Note that except of the title prop/slot, all slots are optional. Therefore, a variety of layouts can be achieved for each layout and thumbnailDisplay combination. Relatedly, slots are not fixed in their place (for example, see #title slot taking place of #aboveTitle when #aboveTitle is not used). Few examples:

• Depending on the thumbnail image dimensions and thumbnailScaleType prop, the image can span across the whole thumbnail area or it can be letterboxed. Scale types correspond to KImg's scaleTypes.

• Depending on the availability of the thumbnail image and thumbnailDisplay prop, a thumbnail area can be filled with light gray color acting as a placeholder area. #thumbnailPlaceholder slot can be used to place content to this area (e.g. learning activity icon).

• All layouts support RTL (right-to-left) languages, for example:

High-level implementation

KCard will consist of two components:

• KCard
  • BaseCard.vue
  • index.vue (this is KCard itself, imports BaseCard)

BaseCard

is a private helper component. It encapsulates the basic logic related to semantic structure, accessibility, shadow, hover, and focus states. Since it won't be exposed as a public component, it won't have a documentation page and the Products won't be allowed to import it. Its purpose is to help with readability and separation of concerns (a11y vs layout). It represents a general card base that won't change even if we completely refactored all layouts implemented in KCard.

KCard

is a final public card component. It will have a page in the documentation. It is built on top of the BaseCard and adds logic related specifically to card content and thumbnails layout.

See issues below for detailed specification of both these components.

Issues

• Implement BaseCard #529
• Implement KCard #530

Out of scope

• Final implementation of the outer dimensions of the card component, card's behavior within a grid (will be part of the card grid specification and work)
• The final implementation of Product card components (products will have their own issues for that)

References

• Product Issue Create KCard Component #445
• Figma Designs of the final Kolibri cards (WIP)

Resources

• Inclusive Components: Cards

[MisRob]

Not for contribution - already assigned to a team member

[MisRob]

Closed by #625. There's couple of minor follow-ups that are now filled in new issues.